Token de Hugging Face: cómo crearlo, almacenarlo y usarlo

Un token de Hugging Face es un Token de Acceso de Usuario que autentica tu máquina, script o trabajo de CI en el Hugging Face Hub. Lo creas en la configuración de tu cuenta bajo la Tokens de acceso pestaña, elige un rol (leen, write o fine-grained), luego ejecuta hf auth login y pégalo o establece HF_TOKEN en tu entorno. Los tokens se ven como hf_....

Qué autoriza realmente el token

Tres cosas, en la práctica: descargar archivos de repositorios privados o bloqueados, enviar archivos a repositorios en los que puedes escribir, y llamar a Proveedores de inferencia como token portador. Los pesos de modelos públicos no necesitan ningún token — hf download gpt2 config.json funciona sin autenticación.

La documentación de Hugging Face describe el token como usable «en lugar de una contraseña» para git y autenticación básica, que es el modelo mental correcto: es una credencial, no una clave de API vinculada a un producto.

Los tres tipos de token

Función	Permisos	Úsalo para
leen	Acceso de lectura a todo repositorio que ya puedas leer, incluidos repositorios privados que tú u tus organizaciones posean	Descargar pesos bloqueados, ejecutar inferencia, notebooks
write	Todo leen lo que hace, más acceso de escritura a repositorios en los que puedas escribir	Enviar checkpoints, editar tarjetas de modelo, ejecuciones de entrenamiento que carguen
fine-grained	Solo los recursos específicos y permisos que marques	Aplicaciones en producción, CI, cualquier cosa compartida con un equipo

Hugging Face recomienda explícitamente tokens de grano fino para uso en producción, con el argumento de que el radio de explosión si uno se filtra es menor y puede compartirse dentro de una organización sin exponer toda tu cuenta. Un patrón de producción típico: un miembro de la org solicita acceso a un modelo bloqueado, luego crea un token de grano fino con acceso de lectura a solo ese repositorio.

Crear un token, paso a paso

1. Inicia sesión, haz clic en tu avatar (arriba a la derecha) → Configuración.
2. Abre el Tokens de acceso pestaña — URL directo huggingface.co/settings/tokens.
3. Haga clic Nuevo token.
4. Nómbralo según la máquina o aplicación que lo albergará (laptop-read, ci-push), no después de ti. Un token por uso es la mejor práctica documentada, para que puedas revocar uno sin romper el resto.
5. Elige el rol. Para grano fino, marca los permisos individuales.
6. Copia el valor inmediatamente. Más tarde solo puedes eliminarlo o actualizarlo desde la misma página mediante Administrar.

Si estás en una org de Equipo o Empresa con una política de tokens, un token de grano fino limitado a esa org puede quedar en un estado Pendiente hasta que un administrador lo apruebe — la lista de tokens muestra un reloj de arena naranja junto a él, y las llamadas a recursos de org devuelven 403 hasta la aprobación.

Iniciar sesión desde la terminal

El CLI enviado con huggingface_hub se llama hf. Instala e inicia sesión:

pip install huggingface_hub
hf auth login

Por defecto, esto ahora ejecuta un flujo de dispositivo de navegador: imprime una URL (https://huggingface.co/oauth/device) y un código corto como ABCD-EFGH. Apruébalo en el navegador y el CLI guarda un token denominado oauth- que se actualiza automáticamente mientras lo sigas usando. Elegir Pega un token de acceso en cambio te permite proporcionar un token que creaste manualmente.

Nota sobre nomenclatura: tutoriales antiguos usan huggingface-cli login. El conjunto de comandos se ha reorganizado bajo hf auth ..., y qué sintaxis acepta tu máquina depende de la huggingface_hub versión instalada — ejecuta hf --help para ver lo que realmente tienes.

Comando	Qué hace
hf auth login --token $HF_TOKEN	Inicio de sesión no interactivo, seguro para scripts
hf auth login --token $HF_TOKEN --add-to-git-credential	También escribe el token en tu gestor de credenciales de git
hf auth login --force	Vuelve a iniciar sesión aunque ya estés autenticado
hf auth whoami	Imprime tu nombre de usuario y organizaciones; falla si no has iniciado sesión
hf auth list	Lista los nombres de tokens almacenados en la máquina
hf auth switch --token-name NAME	Cambia el token activo
hf auth token	Imprime el token activo a stdout
hf auth logout --token-name NAME	Elimina un token almacenado (omite la bandera para eliminar todos)
hf env	Vuelca la ruta del token, si hay un token guardado, y los gestores de git configurados

Pasa el token mediante $HF_TOKEN en lugar de escribir la cadena literal — la documentación advierte contra pegar tokens sin procesar en líneas de comandos donde el historial de shell y los registros de CI pueden capturarlos.

Dónde se almacena el token

Múltiples tokens nombrados viven en un archivo stored_tokens ; el actualmente activo se refleja en un archivo simple token . Ambos se encuentran bajo HF_HOME, que por defecto es ~/.cache/huggingface.

Linux

~/.cache/huggingface/token y ~/.cache/huggingface/stored_tokens. Si XDG_CACHE_HOME está establecido y HF_HOME no lo está, la base se convierte en $XDG_CACHE_HOME/huggingface en su lugar.

macOS

Igual que en Linux: ~/.cache/huggingface/token. Hugging Face no usa ~/Library/Caches aquí, así que no busques allí.

Windows

La ruta se resuelve desde tu directorio de inicio: C:\Users\\.cache\huggingface\token. Dos peculiaridades específicas de Windows que vale la pena conocer. Primero, la caché de modelos usa enlaces simbólicos, que requieren Modo de Desarrollador o un shell de administrador; sin ellos obtienes una advertencia y archivos duplicados en disco, silenciable con HF_HUB_DISABLE_SYMLINKS_WARNING=1. Segundo, si apuntas HF_HUB_CACHE a un NAS compartido con máquinas Linux, establece HF_HUB_DISABLE_SYMLINKS=1 : los enlaces simbólicos creados en Linux no son recorridos de forma fiable en Windows.

Las variables de entorno que importan

Variable	Efecto	Predeterminado
HF_TOKEN	Proporciona el token; anula el token almacenado en disco	sin establecer
HF_TOKEN_PATH	Ubicación desde la cual se lee y escribe el archivo del token	$HF_HOME/token
HF_HOME	Carpeta base para el token y la caché	~/.cache/huggingface
HF_HUB_DISABLE_IMPLICIT_TOKEN	Evita que el token se adjunte automáticamente a solicitudes de lectura que no lo requieren; entonces solo se envía para llamadas de escritura	desactivado
HUGGING_FACE_HUB_TOKEN	Alias obsoleto — aún funciona, pero ya no tiene prioridad sobre HF_TOKEN	—

Dos advertencias importantes. Estas variables se leen en el momento de la importación de huggingface_hub, por lo que establecerlo después de la importación no tiene efecto; reinicie el kernel. Y hf auth logout no puede cerrar su sesión si el token se ha proporcionado mediante HF_TOKEN; debe desestablecer explícitamente la variable.

Usar el token con git

Clonar repositorios grandes mediante HTTPS solicita una contraseña — proporcione el token, no la contraseña de su cuenta:

git clone https://huggingface.co/<usuario>/<repositorio>
# Nombre de usuario: su-nombre-de-usuario-en-hf
# Contraseña: hf_...

Para evitar tener que volver a escribirlo, inicie sesión con la opción --add-to-git-credential, que entrega el token al ayudante de credenciales configurado (store en Linux, Keychain en macOS y Administrador de credenciales de Windows en Windows). Para confirmar qué ayudante está configurado, ejecute hf envgit config --get credential.helper Configured git credential helpers («Ayudantes de credenciales de Git configurados»).

Usar el token para inferencia alojada

El mismo token sirve como credencial de tipo portador (bearer) para los Proveedores de inferencia, que exponen un punto final compatible con OpenAI en https://router.huggingface.co/v1:

curl https://router.huggingface.co/v1/chat/completions 
    -H "Authorization: Bearer $HF_TOKEN" 
    -H 'Content-Type: application/json' 
    -d '{"model": "openai/gpt-oss-120b", "messages": [{"role": "user", "content": "hello"}]}'

Para este uso, un token con permisos finos que tenga el permiso Realizar llamadas a Proveedores de Inferencia es la opción más ajustada. En cuanto a facturación, Hugging Face publica créditos mensuales 0,10 $ para cuentas gratuitas, 2,00 $ para cuentas PRO y 2,00 $ por usuario para organizaciones Team y Enterprisey luego pague según su uso a las tarifas propias del proveedor, sin recargo adicional de Hugging Face. Las organizaciones Team y Enterprise pueden centralizar la facturación mediante el envío de X-HF-Bill-To: mi-nombre-de-organización como cabecera, mientras que cada miembro conserva su propio token.

Esos créditos se agotan rápidamente con los modelos de vanguardia: un modelo como Claude Opus 5, cuyo precio es de 5,00 $ por millón de tokens de entrada y 25,00 $ por millón de tokens de salida consume 2,00 $ en aproximadamente 80 000 tokens de salida. Los modelos de código abierto tienen un coste completamente distinto: Llama 3.3 70B cuesta 0,10 $ por millón de tokens de entrada y 0,32 $ por millón de tokens de salida, y Llama 3.1 8B 0,02 $ por millón de tokens de entrada y 0,03 $ por millón de tokens de salida. Modele su Calculadora de costos de API uso de tokens frente a su volumen antes de integrar un token en cualquier sistema que ejecute bucles.

Modelos bloqueados: el token es necesario pero no suficiente

Para repositorios restringidos —la mayoría de las versiones de Llama y Gemma—, un token válido solo otorga el acceso que ya le haya sido concedido. Según la documentación oficial de modelos restringidos de Hugging Face, la solicitud de acceso en sí misma «solo puede realizarse desde su navegador»: abra la página del modelo mientras tenga una sesión iniciada, complete el formulario y haga clic en Aceptar. La aprobación puede ser automática o manual, y los autores pueden revocarla posteriormente sin previo aviso. Solo entonces hf auth login permitirá la descarga mediante un script. Normalmente verá un 401 cuando no se envíe ningún token y un 403 cuando el token sea válido pero su cuenta no tenga permiso de acceso.

Cuándo no necesitas un token en absoluto

Los pesos públicos sin restricciones se descargan sin credenciales, por lo que una pila puramente local a menudo no requiere ningún token. Ollama extrae imágenes únicamente de su propio registro, y llama.cpp o LM Studio pueden recuperar GGUF públicos de forma anónima. Lo que determina su configuración es la memoria disponible, no la autenticación: Llama 3.1 8B necesita aproximadamente 5 GB de VRAM en cuantización de 4 bits, y Llama 3.3 70B requiere unos 40 GB, mientras que DeepSeek R1 necesita aproximadamente 400 GB y Kimi K3 alrededor de 1,4 TB —territorio de clústeres. Compare sus recursos con la Calculadora de VRAM o el tabla de requisitos de VRAM por modelo.

Solución de problemas

Síntoma	Causa más probable	Corregir
401 No autorizado	No se ha enviado ningún token, o bien se eliminó del lado del servidor	hf auth whoami; vuelva a ejecutar hf auth login --force
403 en un repositorio restringido	El token es válido, pero su cuenta carece de acceso	Solicite acceso desde el navegador, en la página del modelo
403 con el mensaje «revocado por el administrador de la organización»	La organización Enterprise ha revocado el token —de forma permanente	Elimínelo y cree uno nuevo
Funciona en la terminal, pero falla en el notebook	HF_TOKEN establecido tras la importación, o bien un entorno de kernel distinto	Reinicie el kernel; verifique con hf env
Sus modelos privados no aparecen en una lista	HF_HUB_DISABLE_IMPLICIT_TOKEN=1 está activado	Pase token=True establezca explícitamente esta variable o desactívela
Token de lectura rechazado por una organización	La política de la organización permite únicamente tokens con granularidad fina	Genere un token con granularidad fina limitado al ámbito de esa organización

Si un token se filtra

Elimínelo o actualícelo desde la pestaña Tokens de acceso. Si encuentra el token de otra persona —en un repositorio público, un Space o un registro— puede invalidarlo sin poseer la cuenta correspondiente mediante una llamada POST https://huggingface.co/api/credentials/revoke con un cuerpo JSON como {"credentials": ["hf_..."]}. Los tokens coincidentes se anulan inmediatamente y al propietario se le envía un correo electrónico. Este punto final siempre devuelve 202 Aceptado independientemente de si el token existía o no, por lo que no puede usarse maliciosamente para comprobar si un token sigue siendo válido. Para entornos CI, la solución más limpia consiste simplemente en no almacenar ningún token de larga duración: Trusted Publishers intercambia la identidad OIDC de su proveedor de CI por un token temporal de Hub en cada ejecución.

Preguntas frecuentes

¿Es gratuito un token de Hugging Face?

Sí. Crear tokens no tiene ningún costo en ningún nivel de cuenta, y no existe un límite documentado sobre cuántos puede poseer. Los costos solo surgen cuando se usa un token con recursos computacionales de pago: Proveedores de inferencia que excedan sus créditos mensuales, Puntos finales de inferencia (Inference Endpoints), hardware mejorado para Spaces o Trabajos (Jobs).

¿Caducan los tokens de Hugging Face?

Los tokens que crea manualmente en la configuración no tienen fecha de caducidad: permanecen activos hasta que usted los elimine o actualice. La excepción son los tokens generados mediante el flujo de dispositivo del navegador durante hf auth login : estos sí expiran, pero se renuevan automáticamente mientras siga utilizándolos.

¿Cuál es la diferencia entre los permisos de lectura, escritura y granularidad fina?

leen permite descargar cualquier recurso al que ya tenga acceso visible, incluidos repositorios privados. write añade permiso para subir (push). fine-grained parte desde cero y concede únicamente los permisos que usted seleccione explícitamente, razón por la cual Hugging Face lo recomienda para entornos productivos y por la que algunas organizaciones rechazan de plano los tokens de lectura/escritura, exigiendo 403.

¿Puedo usar un mismo token en varias máquinas?

Técnicamente sí, pero la mejor práctica documentada es usar un token por máquina o aplicación: portátil, notebook de Colab, servidor de inferencia. Rotar un token compartido interrumpe simultáneamente a todos sus consumidores; rotar un token específico por máquina afecta únicamente a esa máquina.

¿Necesito un token para ejecutar modelos localmente?

Only for gated or private weights. Public ungated models download anonymously, and Ollama’s registry needs no credentials — see the Guía de instalación de Ollama. Si resulta más conveniente usar una instancia local en lugar de una API suele ser una cuestión económica; la calculadora de autohospedaje frente a API proporciona un umbral de equilibrio al respecto.

¿Dónde coloco el token en Google Colab?

Utilice el panel de secretos de Colab (el icono de llave) para almacenarlo como HF_TOKEN en lugar de codificarlo directamente en una celda, y luego habilite el acceso del cuaderno. Los cuadernos se comprometen y comparten de forma mucho más informal que los archivos fuente, y un token pegado en una celda viaja junto con la copia.

Fuentes

• Centro de Hugging Face — Tokens de acceso de usuario (roles, buenas prácticas, revocación de un token filtrado, políticas de tokens para organizaciones)
• huggingface_hub — Variables de entorno (HF_TOKEN, HF_TOKEN_PATH, HF_HOME valores predeterminados)
• huggingface_hub — Referencia de la CLI (hf auth subcomandos y banderas)
• Proveedores de inferencia — Precios y facturación (créditos mensuales, X-HF-Bill-To)
• Centro de Hugging Face — Modelos restringidos (solicitudes de acceso, flujo de aprobación exclusivo para navegadores)

Los precios de los modelos y las cifras de VRAM provienen de la base de datos de modelos Convly. Compare la capacidad frente al costo en la Clasificación de modelos de lenguaje grande (LLM).