Comment modifier le répertoire du cache Hugging Face

Définissez HF_HOME pour déplacer ensemble la racine Hugging Face et ses caches par défaut. Définissez HF_HUB_CACHE pour ne déplacer que les dépôts téléchargés du Hub. Copiez le cache existant pendant l'arrêt des téléchargements, rendez la variable persistante pour le processus qui l'utilise, puis vérifiez un modèle conservé avant toute suppression.

Les variables HF_HOME et HF_HUB_CACHE ne sont pas interchangeables

Hugging Face expose plusieurs variables de cache car les données locales ne sont pas toutes identiques. Les valeurs par défaut proviennent de HF_HOME, normalement de ~/.cache/huggingface sauf si XDG_CACHE_HOME le modifie.

• HF_HOME déplace la racine Hugging Face utilisée pour l'état des jetons stocké localement et les sous-répertoires de cache par défaut.
• HF_HUB_CACHE déplace le cache des dépôts du Hub — modèles, jeux de données et Spaces — dont la valeur par défaut est $HF_HOME/hub.
• HF_XET_CACHE contrôle le cache des fragments Xet, dont la valeur par défaut est $HF_HOME/xet.
• HF_ASSETS_CACHE contrôle les actifs des bibliothèques en aval, en s'initialisant à $HF_HOME/assets.

Si votre problème concerne le stockage des modèles téléchargés, HF_HUB_CACHE est la substitution la plus ciblée. Si vous souhaitez placer une racine Hugging Face autonome sur un autre disque, HF_HOME est plus simple à appréhender — mais n'oubliez pas que les identifiants et d'autres états peuvent alors suivre cette racine.

Examinez le chemin actif avant de choisir une destination

Utilisez le guide de localisation du cache Hugging Face pour confirmer les variables d'environnement existantes et les substitutions propres aux bibliothèques. Un notebook, un service, un conteneur et un shell interactif peuvent ne pas hériter du même environnement. Le chemin affiché au sein de la charge de travail réelle est plus utile que la valeur d'un shell qu'elle ne voit jamais.

hf cache ls

# Python : voir le cache du Hub résolu par cet environnement
python -c "from huggingface_hub.constants import HF_HUB_CACHE; print(HF_HUB_CACHE)"

Arrêtez les téléchargements et les tâches d'entraînement actifs avant de copier. Le cache contient des instantanés et des blobs partagés ; il est préférable de copier un arbre stable plutôt que de suivre de nouveaux liens pendant qu'un autre processus le modifie.

Rendez le nouveau chemin persistant dans l'environnement correct

Pour un test unique, définissez la variable dans le shell actuel. Pour une utilisation normale, placez-la dans la configuration de l'environnement qui lance la charge de travail : un profil de shell, une unité de service, une définition de conteneur, un noyau de notebook ou un lanceur d'application.

# macOS ou Linux : déplacer uniquement le cache des dépôts du Hub
export HF_HUB_CACHE="/mnt/ai-cache/huggingface/hub"

# Ou déplacer l'ensemble du répertoire d'accueil de Hugging Face
export HF_HOME="/mnt/ai-cache/huggingface"

# Variable d'environnement de l'utilisateur PowerShell
[Environment]::SetEnvironmentVariable(
  "HF_HUB_CACHE",
  "D:\AI-Cache\huggingface\hub",
  "User"
)

Redémarrez l'application après avoir modifié une variable persistante. Les bibliothèques Python résolvent souvent les constantes de cache lors de leur chargement ; modifier l'environnement au milieu d'un processus peut ne pas rediriger le travail déjà en cours.

Copiez, redirigez, vérifiez, puis nettoyez

1. Créez la destination sur un système de fichiers qui prend en charge les liens et les permissions nécessaires à vos charges de travail.
2. Copiez-y l'ancien cache sans réorganiser refs, snapshots ou blobs.
3. Définissez la variable d'environnement choisie et redémarrez la charge de travail.
4. Exécutez hf cache ls --revisions et vérifiez que le dépôt et la révision attendus s'affichent.
5. Chargez hors ligne un modèle connu ou utilisez hf cache verify <repo> pour un dépôt conservé.
6. Effectuez un nouveau téléchargement de petite taille et confirmez qu'il modifie la destination, pas la source.

Conservez le cache d'origine lors d'au moins un redémarrage propre. Si la vérification échoue, restaurez la variable précédente et examinez la copie ou les autorisations. Ne "réparez" pas une migration ratée en fusionnant manuellement deux caches partiels.

Décidez seulement ensuite s'il faut effacer l'ancien cache

Une fois le nouvel emplacement validé, l'ancienne copie peut devenir redondante. Si vous souhaitez également supprimer les dépôts ou révisions obsolètes du nouveau cache, suivez le workflow documenté pour nettoyer en toute sécurité le cache Hugging Face. Le déplacement et l'élagage sont deux opérations distinctes ; les combiner complique l'identification de l'action à l'origine de la disparition d'un modèle.

Pour les familles de modèles irremplaçables, conservez une archive délibérée en dehors du cache actif. Tensor Archive peut préserver les artefacts locaux associés, les vérifier et les restaurer à l'identique. Il ne modifie pas le cache du Hub et ne choisit pas la révision que votre code doit charger.

Réponses liées au stockage

Si la pression vient de plusieurs environnements d'exécution plutôt que d'un seul cache, découvrez comment organiser un modèle de base avec de nombreux adaptateurs. Pour une décision plus large de conservation ou de suppression, utilisez la liste de contrôle de conservation de la bibliothèque locale de modèles.