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

Un token de Hugging Face es un Token de acceso de usuario que autentica su máquina, script o trabajo de CI ante el Hugging Face Hub. Lo crea en la configuración de su cuenta, en la pestaña Tokens de acceso Tokens de accesoleen, write o fine-grainedread, write o fine-grained hf auth login hf auth login HF_TOKEN HF_TOKEN=hf_... hf_....

Qué autoriza exactamente el token

Tres cosas, en la práctica: descargar archivos desde repositorios privados o restringidos, subir archivos a repositorios en los que tenga permisos de escritura y llamar a Proveedores de inferencia como token de tipo bearer. Los pesos de modelos públicos no requieren ningún token: hf download gpt2 config.json funciona sin autenticación.

La documentación oficial de Hugging Face describe el token como utilizable «en lugar de una contraseña» para autenticación básica y para git, lo cual constituye el modelo mental correcto: se trata de una credencial, no de una clave de API vinculada a un único producto.

Los tres tipos de token

Función	Permisos (grants)	Úselo para
leen	Acceso de lectura a todos los repositorios que ya puede leer, incluidos los repositorios privados que usted o sus organizaciones posean	Descargar pesos de modelos restringidos (gated), ejecutar inferencia y notebooks
write	Todo leen lo que hace, además de acceso de escritura a los repositorios en los que puedes escribir	Subida de puntos de control (checkpoints), edición de tarjetas de modelos y ejecuciones de entrenamiento que suben archivos
fine-grained	Solo los recursos y permisos específicos que marques	Aplicaciones de producción, integración continua (CI) o cualquier cosa compartida con un equipo

Hugging Face recomienda explícitamente el uso de tokens de granularidad fina para entornos de producción, ya que, si uno de ellos se filtra, el impacto es menor y puede compartirse dentro de una organización sin exponer toda tu cuenta. Un patrón típico en producción: un miembro de la organización solicita acceso a un modelo restringido y luego genera un token de granularidad fina con permiso de lectura únicamente para ese repositorio.

Creación paso a paso de un token

1. Inicia sesión, haz clic en tu avatar (esquina superior derecha) → Configuración.
2. Abre el archivo Tokens de acceso pestaña — URL directa huggingface.co/settings/tokens.
3. Haga clic Nuevo token.
4. Asígnale un nombre según la máquina o aplicación que lo almacenará (por ejemplo,laptop-read, ci-push), no según tu nombre personal. La práctica recomendada documentada consiste en usar un token distinto por cada caso de uso, para poder revocar uno sin afectar al resto.
5. Selecciona el rol. Para tokens de granularidad fina, marca los permisos individuales.
6. Copia inmediatamente su valor. Posteriormente solo podrás eliminarlo o renovarlo desde la misma página mediante Administrar.

Si perteneces a una organización de tipo Team o Enterprise con una política de tokens, un token de granularidad fina limitado a esa organización podría quedar en 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 la organización devuelven 403 hasta que se apruebe.

Inicio de sesión desde la terminal

La CLI incluida con huggingface_hub se llama hf. Instálala e inicia sesión:

pip install huggingface_hub
hf auth login

De forma predeterminada, ahora utiliza un flujo de dispositivo con navegador: imprime una URL (https://huggingface.co/oauth/device) y un código corto como ABCD-EFGH. Apruébalo en el navegador y la CLI guardará un token denominado oauth-<nombredeusuario> , que se renovará automáticamente mientras sigas usándolo. Si eliges Pegar un token de acceso en su lugar, podrás proporcionar un token que hayas creado manualmente.

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

Comando	Qué hace
hf auth login --token $HF_TOKEN	Inicio de sesión sin interacción, seguro para scripts
hf auth login --token $HF_TOKEN --add-to-git-credential	También escribe el token en tu helper de credenciales de Git
hf auth login --force	Vuelve a iniciar sesión incluso si ya estás autenticado
hf auth whoami	Muestra tu nombre de usuario y organizaciones; devuelve un error si no has iniciado sesión
hf auth list	Enumera los nombres de los tokens almacenados en la máquina
hf auth switch --token-name NOMBRE	Cambia el token activo
hf auth token	Imprime el token activo en la salida estándar
hf auth logout --token-name NOMBRE	Elimina un token almacenado (omite la bandera para eliminarlos todos)
hf env	Muestra la ruta del token, si se ha guardado algún token y los helpers 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 la shell y los registros de CI podrían capturarlos.

Dónde se almacena el token

Varios tokens con nombre se almacenan en un archivo stored_tokens ; el token actualmente activo se refleja también en un archivo sencillo llamado token . Ambos archivos residen dentro de HF_HOME, cuyo valor predeterminado es ~/.cache/huggingface.

Linux

~/.cache/huggingface/token y ~/.cache/huggingface/stored_tokens. Si está definida la variable XDG_CACHE_HOME y no lo está HF_HOME HF_HOME , la ruta base pasa a ser $XDG_CACHE_HOME/huggingface

macOS

Igual que en Linux: ~/.cache/huggingface/token. Hugging Face no utiliza ~/Library/Caches aquí, así que no lo busque en esa ubicación.

Windows

La ruta se resuelve desde su directorio personal: C:\Users\\.cache\huggingface\token. Dos particularidades específicas de Windows que vale la pena conocer. Primero, la caché de modelos emplea enlaces simbólicos, que requieren el modo de desarrollador o una terminal con privilegios de administrador; sin ellos, recibirá una advertencia y se duplicarán los archivos en disco (esto puede silenciarse mediante HF_HUB_DISABLE_SYMLINKS_WARNING=1). Segundo, si apunta HF_HUB_CACHE a un NAS compartido con equipos Linux, debe establecer HF_HUB_DISABLE_SYMLINKS=1 : los enlaces simbólicos creados en Linux no son recorridos de forma fiable en Windows.

Variables de entorno relevantes

Variable	Efecto	Predeterminado
HF_TOKEN	Proporciona el token; anula el token almacenado en disco	sin definir
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.

Uso del 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»).

Uso del 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 restringidos (gated): 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 necesita 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 La bandera 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?

Solo para pesos restringidos o privados. Los modelos públicos no restringidos se descargan de forma anónima, y el registro de Ollama no requiere credenciales; véase la 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).