Cache local du Hub

Ce document décrit la structure sur disque du cache local du HF Hub. Il est destiné à servir de référence pour réimplémenter le système de cache dans n’importe quel langage.

Voici une liste partielle des bibliothèques et applications qui utilisent cette disposition de cache. Veuillez ouvrir une PR pour ajouter la vôtre.

Bibliothèques

Applications

Emplacement du cache

Le répertoire de cache par défaut est :

~/.cache/huggingface/hub

Cela peut être remplacé par des variables d'environnement :

• HF_HUB_CACHE - chemin direct vers le répertoire de cache (prioritaire)
• HF_HOME - chemin du répertoire principal Hugging Face ; s'il est défini, le cache se trouve dans $HF_HOME/hub

Aperçu

<CACHE_DIR>/
├── .locks/                                  # Lock files for concurrent download safety
├── blobs/                                   # Shared blob store: Xet files deduplicated across repos
├── models--<org>--<repo>/                   # Cached model repositories
├── datasets--<org>--<repo>/                 # Cached dataset repositories
└── spaces--<org>--<repo>/                   # Cached space repositories

Chaque dépôt téléchargé reçoit un dossier unique et plat. À l’intérieur de chaque dossier de dépôt, les fichiers sont stockés une seule fois dans un répertoire blobs/ adressé par contenu et accédés via des liens symboliques snapshots/. Les références nommées (branches, étiquettes) sont suivies dans refs/. Depuis huggingface_hub 1.32, les fichiers téléchargés avec hf_xet sont stockés une seule fois pour l’ensemble du cache, dans un stockage de blobs partagé à la racine du cache. L’entrée blobs/ du dépôt est alors un lien symbolique vers ce fichier.

Schéma

                     ┌──────────────────────────────────────────┐
                     │           Repository folder              │
                     │  models--julien-c--EsperBERTo-small      │
                     └──────────────┬───────────────────────────┘
                                    │
              ┌─────────────┬───────┴───────┬──────────────┐
              │             │               │              │
              v             v               v              v
          ┌───────┐    ┌────────┐    ┌────────────┐   ┌──────────┐
          │ refs/ │    │ blobs/ │    │ snapshots/ │   │.no_exist/│
          └───┬───┘    └────┬───┘    └──────┬─────┘   └────┬─────┘
              │             │               │              │
              │             │               │              │
   "main" contains     Files stored     One folder     Empty marker
   commit hash         by content       per commit     files for
   e.g. "aaaaaa"       hash (SHA-1      hash, e.g.     files known
                       or SHA-256)      aaaaaa/        not to exist
   Resolves a                           bbbbbb/
   branch/tag to                            │
   a snapshot ──────────────────────►  Contains symlinks
                                       to ../../blobs/{hash}

Nommage des dossiers de dépôt

Les dépôts sont stockés sous forme de répertoires plats à la racine du cache. Le nom du dossier encode le type de dépôt et l'identifiant du dépôt :

{type}s--{repo_id_with_slashes_replaced_by_--}

Règles :

• Le type de dépôt est au pluriel : models, datasets, spaces
• Les barres obliques (/) dans l'identifiant du dépôt sont remplacées par --
• Le séparateur entre toutes les parties est --
• La casse est préservée

Exemples :

Les buckets ne sont pas gérés par ce cache car ils ne sont pas basés sur git. Utilisez à la place la commande dédiée hf buckets sync.

Dans un dossier de dépôt

Chaque dépôt mis en cache possède la même structure interne :

<repo_folder>/
├── blobs/
├── refs/
├── snapshots/
└── .no_exist/    # may not always be present

blobs/ : stockage de fichiers par adresse de contenu

Le répertoire blobs/ stocke le contenu réel des fichiers. Chaque fichier est nommé d’après son etag de fichier sur le Hub :

• Fichiers suivis par Git : nommés par leur hachage SHA-1 (40 caractères hexadécimaux)
• Fichiers Git LFS : nommés par leur hachage SHA-256 (64 caractères hexadécimaux)

Ceci est un répertoire à plat — sans sous-répertoires. Les fichiers identiques entre différentes révisions ne sont stockés qu’une seule fois. Une entrée est soit un fichier régulier, soit un lien symbolique relatif vers le stockage de blobs partagé ; les lecteurs doivent le suivre.

blobs/
├── 403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd   # SHA-256 (LFS)
├── 7cb18dc9bafbfcf74629a4b760af1b160957a83e                           # SHA-1 (git)
└── d7edf6bd2a681fb0175f7735299831ee1b22b812                           # SHA-1 (git)

refs/ : références de branches et de tags

Le répertoire refs/ associe les références lisibles par l'homme (noms de branches, étiquettes, numéros de PR) aux hachages de commit.

Chaque référence est un fichier texte simple contenant une seule ligne : l’empreinte de commit complète (40 caractères hexadécimaux).

refs/
├── main            # contains e.g. "bbc77c8132af1cc5cf678da3f1ddf2de43606d48"
├── 2.4.0           # a tag
└── refs/
    └── pr/
        └── 1       # pull request reference

Lorsqu'un fichier est téléchargé à l'aide du nom d'une branche ou d'un tag, le fichier de référence correspondant est créé ou mis à jour avec le dernier hachage de commit.

snapshots/ : vues de révision

Le répertoire snapshots/ contient un sous-répertoire par révision mise en cache (hash de commit). Chaque répertoire de révision reproduit la structure des fichiers du dépôt sur le Hub, mais les fichiers sont des liens symboliques pointant vers ../../blobs/{hash}.

snapshots/
├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
│   ├── README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
│   └── pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
└── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/
    ├── README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
    └── pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd

Propriétés clés :

• Les liens symboliques utilisent des chemins relatifs : ../../blobs/{hash}
• Si un fichier n'est pas modifié entre deux révisions, les deux liens symboliques pointent vers le même blob sans duplication de données
• Les fichiers situés dans des sous-répertoires sur le Hub sont représentés sous forme de sous-répertoires dans l'instantané (le chemin relatif complet est conservé)

Le passage d'un instantané à un autre est similaire à l'utilisation de git checkout dans un dépôt git local.

.no_exist/ : cache d'inexistence

Le répertoire .no_exist/ suit les fichiers qui ont été demandés mais qui n'existent pas sur le Hub. Cela évite les requêtes HTTP répétées pour les fichiers facultatifs.

La structure reflète celle de snapshots/ : un sous-répertoire par hachage de commit, contenant des fichiers vides (et non des liens symboliques) nommés d’après le fichier manquant.

.no_exist/
└── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
    └── config_that_does_not_exist.json    # empty file

L'utilisation du disque est négligeable, car il ne s'agit que de fichiers marqueurs vides.

Stockage de blobs partagé

Les fichiers téléchargés via Xet sont dédupliqués entre les dépôts. Un tel fichier est stocké une seule fois à la racine du cache, sous blobs/, et chaque dépôt qui en a besoin reçoit un lien symbolique relatif au lieu d’une copie :

<CACHE_DIR>/
├── blobs/
│   ├── .huggingface-shared-blobs                 # marker file, contains the layout version ("1")
│   └── 73/                                       # first two hex characters of the Xet hash
│       ├── 73b079dc7bd546aed26d20a82289bd752fc52a2fda13e7f2b551f3af73845b59                       # the file, named by its Xet hash (64 hex characters)
│       ├── 73b079dc7bd546aed26d20a82289bd752fc52a2fda13e7f2b551f3af73845b59.refs                  # manifest: one line per repo blob that references it (path relative to the cache root)
│       └── 73b079dc7bd546aed26d20a82289bd752fc52a2fda13e7f2b551f3af73845b59.lock                  # lock file
│
└── models--HuggingFaceTB--SmolLM2-135M-Instruct/
    └── blobs/
        └── 5af571cbf074e6d21a03528d2330792e532ca608f24ac70a143f6b369968ab8c -> ../../blobs/73/73b079dc7bd546aed26d20a82289bd752fc52a2fda13e7f2b551f3af73845b59

Propriétés clés :

• L'entrée du dépôt conserve son nom d'etag et devient un lien symbolique relatif : ../../blobs/{xet_hash[:2]}/{xet_hash}
• La structure snapshots/ ne change pas, donc la résolution des fichiers n'est pas affectée
• Le fichier marqueur identifie le magasin : un répertoire blobs/ non vide à la racine du cache sans ce fichier n'est jamais utilisé ni modifié
• Le store nécessite des liens symboliques et hf_xet. En cas d’échec du partage, le fichier est stocké dans le dossier du dépôt comme auparavant. HF_HUB_DISABLE_SHARED_BLOBS=1 désactive le store
• Seules les nouvelles téléchargements passent par le store. Les fichiers écrits par des versions antérieures ou par d'autres clients restent des fichiers réguliers dans le dossier du dépôt, de sorte qu'un cache peut contenir les deux

Les implémentations qui ne font que lire le cache n’ont besoin d’aucune modification : le suivi des liens symboliques fonctionne comme avant.

Les implémentations qui suppriment des éléments du cache doivent considérer un blob de dépôt qui est un lien symbolique comme une référence vers le magasin :

• Supprimez le lien symbolique dans blobs/ du dépôt, et non le fichier partagé vers lequel il pointe
• Verrouiller <xet_hash>.lock avant de vérifier le manifeste et de supprimer
• Supprimez le fichier partagé et son .refs uniquement si aucun lien symbolique répertorié dans le manifeste ne pointe encore vers ce fichier
• Si le manifest est manquant ou illisible, conservez le fichier partagé

Consultez le guide de la cache huggingface_hub pour connaître le comportement de suppression et les limitations liées aux anciens clients.

Fichiers de verrouillage

Les fichiers de verrouillage empêchent les processus concurrents de télécharger le même blob simultanément. Ils sont stockés dans un répertoire .locks/ à la racine du cache (et non à l’intérieur du dossier du dépôt) :

<CACHE_DIR>/.locks/<repo_folder_name>/<blob_hash>.lock

Exemple :

<CACHE_DIR>/.locks/models--julien-c--EsperBERTo-small/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd.lock

Exemple complet

~/.cache/huggingface/hub/
├── .locks/
│   └── models--julien-c--EsperBERTo-small/
│       └── 403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd.lock
│
└── models--julien-c--EsperBERTo-small/
    ├── blobs/
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    │
    ├── refs/
    │   └── main    # contains "bbc77c8132af1cc5cf678da3f1ddf2de43606d48"
    │
    ├── snapshots/
    │   ├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
    │   │   ├── README.md         -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
    │   │   └── pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   │
    │   └── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/
    │       ├── README.md         -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │       └── pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │
    └── .no_exist/
        └── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
            └── optional_config.json    # empty file

Notez que pytorch_model.bin pointe vers le même blob dans les deux révisions. Le fichier de 321 Mo est stocké une seule fois sur le disque.

Logique de résolution des fichiers

Pour localiser un fichier en cache sur le disque :

1. Résoudre la révision en hachage de commit

   • Si la révision est déjà une chaîne hexadécimale de 40 caractères, utilisez-la directement
   • Sinon, lisez le fichier refs/{revision} pour obtenir l'identifiant de commit

2. Vérifier l'instantané

   • Recherchez snapshots/{commit_hash}/{relative_path}
   • S'il existe (en tant que lien symbolique ou fichier), le fichier est mis en cache. Suivez le lien symbolique pour obtenir le contenu

3. Vérifier l'inexistence

   • Recherchez .no_exist/{commit_hash}/{relative_path}
   • S'il existe, le fichier est connu pour ne pas exister sur le Hub pour cette révision

4. Manquement de cache

   • Si aucun des deux chemins n'existe, le fichier n'a pas encore été mis en cache

Comportement sous Windows

Le cache repose sur des liens symboliques. Sur les systèmes Windows où les liens symboliques ne sont pas disponibles, le cache fonctionne en mode dégradé : des copies réelles des fichiers sont placées directement dans snapshots/ au lieu de liens symboliques. Le répertoire blobs/ et le stockage de blobs partagé ne sont pas utilisés dans ce mode.

Cela signifie que le même contenu de fichier peut être dupliqué entre les révisions, augmentant ainsi l’utilisation du disque. Pour activer la prise en charge des liens symboliques sur Windows, activez le Mode développeur ou exécutez en tant qu’administrateur.