Cómo cambiar el directorio de la caché de Hugging Face

Establece HF_HOME cuando quieras mover juntos el directorio principal de Hugging Face y sus cachés predeterminadas. Establece HF_HUB_CACHE cuando solo quieras reubicar los repositorios descargados del Hub. Copia la caché existente con las descargas detenidas, haz permanente la variable para el proceso que la utiliza y después verifica un modelo conservado antes de eliminar nada.

HF_HOME y HF_HUB_CACHE no son intercambiables

Hugging Face expone varias variables de caché porque no todos los datos locales son iguales. Los valores predeterminados se derivan de HF_HOME, normalmente ~/.cache/huggingface, salvo que XDG_CACHE_HOME lo modifique.

• HF_HOME mueve el directorio principal de Hugging Face que se utiliza para el estado de los tokens almacenados localmente y los subdirectorios de caché predeterminados.
• HF_HUB_CACHE mueve la caché de repositorios del Hub —modelos, conjuntos de datos y Spaces—, cuyo valor predeterminado es $HF_HOME/hub.
• HF_XET_CACHE controla la caché de fragmentos de Xet, cuyo valor predeterminado es $HF_HOME/xet.
• HF_ASSETS_CACHE controla los recursos de bibliotecas dependientes, cuyo valor predeterminado es $HF_HOME/assets.

Si el problema es el almacenamiento de modelos descargados, HF_HUB_CACHE es la sustitución más específica. Si quieres una única raíz autónoma de Hugging Face en otro disco, HF_HOME resulta más fácil de entender, pero recuerda que las credenciales y otros estados pueden seguir también a esa raíz.

Comprueba la ruta activa antes de elegir un destino

Usa la guía de ubicación de la caché de Hugging Face para confirmar las variables de entorno existentes y las sustituciones específicas de bibliotecas. Un notebook, servicio, contenedor y shell interactivo pueden no heredar el mismo entorno. La ruta impresa dentro de la carga de trabajo real es más útil que el valor de un shell que nunca utiliza.

hf cache ls

# Python: consulta la caché del Hub resuelta por este entorno
python -c "from huggingface_hub.constants import HF_HUB_CACHE; print(HF_HUB_CACHE)"

Detén las descargas y tareas de entrenamiento activas antes de copiar. La caché contiene instantáneas y blobs compartidos; es mejor copiar un árbol estable que perseguir enlaces nuevos mientras otro proceso lo modifica.

Haz que la ruta nueva sea permanente en el entorno adecuado

Para una prueba puntual, establece la variable en el shell actual. Para el uso normal, inclúyela en la configuración del entorno que inicia la carga de trabajo: un perfil del shell, una unidad de servicio, una definición de contenedor, un kernel de notebook o un lanzador de aplicaciones.

# macOS o Linux: mueve solo la caché de repositorios del Hub
export HF_HUB_CACHE="/mnt/ai-cache/huggingface/hub"

# O mueve todo el directorio principal de Hugging Face
export HF_HOME="/mnt/ai-cache/huggingface"

# Variable de entorno de usuario de PowerShell
[Environment]::SetEnvironmentVariable(
  "HF_HUB_CACHE",
  "D:\AI-Cache\huggingface\hub",
  "User"
)

Reinicia la aplicación después de cambiar una variable permanente. Las bibliotecas de Python suelen resolver las constantes de caché al importarlas; cambiar el entorno a mitad de un proceso puede no redirigir el trabajo que ya está en curso.

Copia, configura la ruta, verifica y después limpia

1. Crea el destino en un sistema de archivos compatible con los enlaces y permisos que requieren tus cargas de trabajo.
2. Copia la caché antigua en él sin reorganizar refs, snapshots ni blobs.
3. Establece la variable de entorno elegida y reinicia la carga de trabajo.
4. Ejecuta hf cache ls --revisions y confirma que aparecen el repositorio y la revisión esperados.
5. Carga un modelo conocido sin conexión o utiliza hf cache verify <repo> para un repositorio conservado.
6. Realiza una descarga nueva y pequeña y confirma que cambia el destino, no el origen.

Conserva la caché original durante al menos un reinicio limpio. Si la verificación falla, restaura la variable anterior e investiga la copia o los permisos. No intentes «corregir» una migración fallida fusionando manualmente dos cachés parciales.

Solo entonces decide si quieres borrar la caché antigua

Cuando hayas comprobado el destino, la copia antigua puede ser redundante. Si también quieres eliminar repositorios o revisiones obsoletos dentro de la caché nueva, utiliza el flujo documentado para borrar la caché de Hugging Face con seguridad. La reubicación y la poda son operaciones distintas; combinarlas dificulta saber qué acción provocó la ausencia de un modelo.

Para familias de modelos irreemplazables, conserva un archivo intencionado fuera de la caché activa. Tensor Archive puede conservar artefactos locales relacionados, verificarlos y restaurarlos exactamente. No modifica la caché del Hub ni elige qué revisión debe cargar tu código.

Respuestas relacionadas sobre almacenamiento

Si la presión procede de varios entornos de ejecución y no de una sola caché, consulta cómo organizar un modelo base con muchos adaptadores. Para una decisión más amplia sobre qué conservar o eliminar, utiliza la lista de comprobación para conservar una biblioteca local de modelos.