AskClean

Cómo limpiar la caché de Hugging Face en el Mac

Equipo de AskClean · Actualizado 2026-11-02

Para recuperar el espacio que ocupa la caché de Hugging Face en el Mac, localiza la caché que usa realmente tu aplicación, revísala con hf cache ls y previsualiza un repositorio o una revisión concretos con hf cache rm --dry-run. Conserva los modelos que necesitas sin conexión y tu propio trabajo. No borres a ciegas los blobs compartidos ni la carpeta HF_HOME entera.

Ilustración conceptual de revisiones de modelos conectadas a bloques de datos compartidos, con los archivos del proyecto guardados aparte
Varias revisiones pueden compartir los mismos archivos. Guarda por separado tus checkpoints y tu trabajo. Ilustración conceptual.

Localiza los datos y protege tu trabajo

La ubicación habitual es ~/.cache/huggingface/hub. HF_HUB_CACHE selecciona directamente la caché de repositorios del Hub; HF_HOME cambia la carpeta principal de Hugging Face, que abarca más datos, y si HF_HOME no está definido, XDG_CACHE_HOME puede influir en la ruta predeterminada. Una aplicación también puede elegir otra ruta con cache_dir. Comprueba por separado las aplicaciones gráficas, la terminal y los notebooks. HF_HOME puede contener datos de autenticación: no lo borres entero ni compartas su contenido.

Los checkpoints ajustados, los adaptadores, los cambios del tokenizer, las conversiones, los datos privados y la configuración del proyecto pueden no estar disponibles para volver a descargarlos. Comprueba que tu copia de seguridad los incluye de verdad: algunas herramientas excluyen las cachés marcadas con CACHEDIR.TAG. Si no sabes cómo restaurar algo, consérvalo, y no decidas solo por la fecha del último acceso.

Muestra los ID completos y las advertencias

Cierra las aplicaciones, descargas y tareas que usen la caché. Ejecuta hf cache ls --no-truncate y después hf cache ls --revisions --no-truncate --show-warnings. En la versión probada, las advertencias detalladas están ocultas por defecto. Si usas una caché personalizada, pasa siempre el mismo --cache-dir. Investiga los errores de lectura o de estructura, anota el uso y el espacio libre, y no compartas listas que revelen repositorios confidenciales.

Revisa el alcance antes de confirmar

hf cache rm necesita el ID completo que muestra la CLI. Para un repositorio de modelos, conserva el prefijo model/; no lo sustituyas por el nombre de una carpeta que empiece por models--. Para una revisión, usa el hash completo y confirma a qué repositorio pertenece. Empieza siempre con --dry-run: la salida resume los objetivos y el espacio estimado, pero no enumera cada archivo. Si eliges un repositorio, se incluyen todas sus revisiones en caché.

Una vez comprobado, repite el comando sin --dry-run con el mismo objetivo y la misma ruta, y deja activada la confirmación. Si la selección cambia o la vista previa falla, detente e investiga. Los archivos se eliminan directamente, sin pasar por la Papelera: recuperarlos exige una copia de seguridad o volver a descargarlos. Las snapshots (y, en algunas estructuras, distintos repositorios) comparten blobs: deja las referencias en manos del gestor de caché y no sumes sin más los tamaños que se muestran.

Distingue prune de las demás cachés

En la versión 2.0.0 probada, hf cache prune --dry-run previsualiza las revisiones detached y las descargas incompletas. Un proyecto puede fijar una revisión exacta aunque no tenga una referencia con nombre, y una descarga incompleta puede pertenecer a una tarea que sigue en marcha. Revisa cada objetivo, detén las descargas activas y empieza por un solo elemento bien identificado.

Los datos que genera Hugging Face Datasets en HF_DATASETS_CACHE son distintos de las descargas del Hub. Revisa también por separado los datos de transferencia de Xet y las carpetas descargadas con local_dir, y conserva tus modificaciones locales. Borrar HF_HOME entero no sustituye esta revisión.

Carga los modelos que conservas

Repite las mediciones, carga los modelos y las revisiones que necesitas y ejecuta una tarea pequeña con un resultado conocido: importar una biblioteca de Python no basta. Si los necesitas sin conexión, pruébalo desconectando de verdad la red. Si algo falla, detén la limpieza y revisa el entorno, las rutas, los archivos, los permisos de acceso y el espacio antes de recuperar nada. Si un modelo necesario se vuelve a descargar una y otra vez, replantéate la selección o la capacidad.

Para mover la caché a un disco externo, comprueba el espacio, los permisos y que el disco admita enlaces simbólicos. Copia los enlaces junto con sus destinos, configura cada aplicación y prueba los modelos antes de retirar el original. Mantén el disco conectado mientras lo usen.

Qué verificamos

El 29 de septiembre de 2026 probamos sin red cachés sintéticas temporales con huggingface_hub 2.0.0: listados, ID completos, advertencias y dry-run. Las vistas previas no modificaron archivos, y eliminar una revisión antigua conservó la actual y los datos compartidos. No verificamos inferencia real, cachés de usuarios, la limpieza de blobs compartidos entre repositorios ni migraciones de disco, y no garantizamos ninguna cantidad de espacio. Consulta hf cache --help en tu versión.

Qué se puede recrear y qué hay que conservar

Revisa cada categoría por separado. La tabla explica qué debes conservar o cómo recuperarlo; no marca archivos para borrarlos automáticamente.

ElementoDónde comprobarloQué revisar antes de borrar
Repositorio o revisión del Hubhf cache ls --revisionsComprueba la selección exacta. Recuperarla puede requerir otra descarga y acceso al mismo repositorio.
Blobs y snapshots compartidosCaché del Hub verificadaUsa el gestor de caché: las revisiones y, en algunas estructuras, los repositorios pueden compartir los mismos archivos.
Revisiones detachedhf cache prune --dry-runUn proyecto puede necesitar esa revisión exacta aunque la caché no tenga una referencia con nombre.
Caché de datasets generadosHF_DATASETS_CACHEVa aparte de las descargas del Hub; recrearla puede exigir tiempo de procesamiento y los datos de origen.
Checkpoints, adaptadores y código propiosTu proyecto y tus copias de seguridadConserva tu trabajo original y comprueba que las copias de seguridad lo incluyen, sobre todo si está dentro de una carpeta de caché.
Carpeta principal de Hugging Face y autenticaciónHF_HOMEPuede contener datos de autenticación: no borres la carpeta entera para quitar entradas de la caché de modelos.

La prueba local usó una caché sintética diminuta; su tamaño no es una referencia ni una estimación del ahorro real.

Preguntas frecuentes

¿Puedo borrar ~/.cache/huggingface en el Mac?

No trates esa carpeta entera como prescindible. Localiza la caché del Hub que está activa, conserva los datos de autenticación y tu trabajo original, y previsualiza repositorios o revisiones concretos con la interfaz hf cache instalada.

¿Por qué borrar una revisión libera menos de lo que indica su tamaño?

Las revisiones pueden compartir archivos, y algunas estructuras también los comparten entre repositorios. Consulta la estimación de la vista previa y compara el uso del disco y el espacio libre antes y después: sumar los tamaños mostrados puede contar los mismos archivos varias veces.

¿Una revisión detached ya no se usa?

No necesariamente. Un proyecto puede fijar la revisión exacta aunque no haya una referencia con nombre. Revisa antes los requisitos del proyecto.

¿hf cache rm puede borrar mi modelo ajustado?

Sí, si está dentro del objetivo seleccionado. Sácalo del alcance del borrado y comprueba su copia de seguridad: que una carpeta se llame cache no convierte tu trabajo en prescindible.

Fuentes

Más guías sobre almacenamiento de modelos y desarrollo