Hub Python Library documentation
Interfaz de línea de comandos (CLI)
Interfaz de línea de comandos (CLI)
El paquete de Python huggingface_hub incluye una CLI integrada llamada hf. Esta herramienta te permite interactuar con Hugging Face Hub directamente desde una terminal. Por ejemplo, puedes iniciar sesión en tu cuenta, crear un repositorio, subir y descargar archivos, etc. También cuenta con funciones prácticas para configurar tu máquina o gestionar tu caché. En esta guía, veremos las principales funciones de la CLI y cómo usarlas.
Esta guía cubre las funciones más importantes de la CLI
hf. Para una referencia completa de todos los comandos y opciones, consulte la referencia de la CLI.
¿Usas la CLI
hfcon agentes de IA? Instala la Skill y consulta la guía Hugging Face CLI for AI Agents.# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills` hf skills addEl instalador independiente lo instala por ti (ver abajo) y
hf updatelo actualiza.
Primeros pasos
Instalador independiente (Recomendado)
Puedes instalar la CLI hf con un solo comando:
En macOS y Linux:
>>> curl -LsSf https://hf.co/cli/install.sh | bashEn Windows:
>>> powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"El instalador también instala la habilidad hf-cli de forma global, para Claude Code y cualquier agente que lea ~/.agents/skills. Pasa --exclude-skill para omitirla:
>>> curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill>>> powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://hf.co/cli/install.ps1))) -ExcludeSkill"Una vez instalado, puedes comprobar que la CLI está configurada correctamente:
>>> hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...
Hugging Face Hub CLI
Options:
--skills Print the `hf-cli` SKILL.md to stdout (alias for `hf skills preview`).
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or customize the installation.
-h, --help Show this message and exit.
Main commands:
auth Manage authentication (login, logout, etc.).
buckets Commands to interact with buckets.
cache Manage local cache directory.
collections Interact with collections on the Hub.
datasets Interact with datasets on the Hub.
download Download files from the Hub.
endpoints Manage Hugging Face Inference Endpoints.
extensions Manage hf CLI extensions.
jobs Run and manage Jobs on the Hub.
models Interact with models on the Hub.
papers Interact with papers on the Hub.
repos Manage repos on the Hub.
skills Manage skills for AI assistants.
spaces Interact with spaces on the Hub.
sync Sync files between local directory and a bucket.
upload Upload a file or a folder to the Hub.
Help commands:
env Print information about the environment.
version Print information about the hf version.Si la CLI está instalada correctamente, debería ver una lista de todas las opciones disponibles en la CLI. Si recibe un mensaje de error como command not found: hf, consulte la guía de Instalación.
La opción
--helpes muy útil para obtener más detalles sobre un comando. Puedes usarla en cualquier momento para listar todas las opciones disponibles y sus detalles. Por ejemplo,hf upload --helpproporciona más información sobre cómo subir archivos usando la CLI.
Usando uv
La forma más sencilla de usar la CLI hf es con uvx. Siempre ejecuta la última versión en un entorno aislado, ¡sin necesidad de instalar nada!
Asegúrate de que uv esté instalado primero. Consulta la guía de instalación de uv para obtener instrucciones.
Luego, usa la CLI directamente:
>>> uvx hf auth login
>>> uvx hf download
>>> uvx hf ...
uvx hfutiliza el paquete de PyPIhf.
Instalar con pip
La CLI también se distribuye con el paquete principal huggingface_hub:
>>> pip install -U "huggingface_hub"Usando Homebrew
También puedes instalar la CLI usando Homebrew:
>>> brew install hfPuedes consultar la página de Homebrew de huggingface aquí para obtener más detalles.
Actualizando
Para actualizar a la última versión, ejecute:
>>> hf updateEsto detecta cómo se instaló hf (Homebrew, instalador independiente o pip) y ejecuta el comando de actualización correspondiente. Si la habilidad hf-cli está instalada de forma global, también se actualiza para que los agentes vean la nueva interfaz de comandos. Si no está instalada, permanece desinstalada: la actualización nunca la reinstala si la omitiste o la eliminaste.
Por defecto, la CLI también imprime una advertencia de una línea en amarillo en stderr cuando hay una versión más nueva disponible en PyPI. Para silenciarla (p. ej. en CI sin conexión), establezca HF_HUB_DISABLE_UPDATE_CHECK=1.
Formato de salida
La mayoría de los comandos hf aceptan el mismo conjunto de banderas de formato globales. Se documentan en una sección dedicada a Formatting options en cada página de --help y se pueden añadir a cualquier comando sin tener que declararlas por comando:
| Flag | Equivalente | Descripción |
|---|---|---|
--format <value> | — | Elija el formato de salida de forma explícita. Valores aceptados: auto (predeterminado), human, agent, json, quiet. |
--json | --format json | Imprime JSON estructurado. Útil para enviarlo a jq u otros scripts. |
-q, --quiet | --format quiet | Imprime solo los IDs (uno por línea). Útil para pasar los IDs a otros comandos. |
--no-truncate | — | Muestra los valores completos en las tablas humanas en lugar de acortar los valores largos con .... La tabla puede exceder el ancho de la terminal. Usa --format json para una salida estructurada de columnas de lista/diccionario. |
auto (el valor predeterminado) selecciona human para una terminal interactiva y agent cuando la CLI es invocada por un agente de IA. human añade colores y tablas formateadas; agent produce valores separados por tabulaciones sin truncamiento; json emite un objeto o array JSON compacto. Mezclar dos banderas de modo de salida (p. ej. --json junto con --format table) genera un error de uso.
Las tablas humanas se ajustan automáticamente al ancho de tu terminal: las columnas más anchas se acortan solo cuando los anchos naturales desbordan la pantalla (así, en una terminal ancha, normalmente ves los valores completos sin ...). Pasa --no-truncate para forzar los valores completos sin importar el ancho; usa --format json para una salida estructurada de columnas de lista/diccionario.
# JSON output for scripting
>>> hf models ls --search bert --limit 2 --json | jq '.[].id'
# IDs only, one per line
>>> hf collections ls --owner nvidia -q
nvidia/nemotron-supervised-fine-tuning-69eab9824c9120a3a3b1e25e
nvidia/nvidia-nemotron-v3-69388dda16167bb1607171eahf auth login
En muchos casos, debes iniciar sesión en una cuenta de Hugging Face para interactuar con el Hub (descargar repositorios privados, subir archivos, crear PR, etc.). Para hacerlo, ejecuta el siguiente comando en tu terminal:
>>> hf auth loginSi ya has iniciado sesión, este comando omitirá la solicitud y mostrará un mensaje. Para forzar un nuevo inicio de sesión (p. ej., para cambiar de tokens), usa --force:
>>> hf auth login --forcePor defecto, el comando inicia sesión con tu navegador: imprime una URL y un código corto. Abre la URL, introduce el código, aprueba la solicitud y la CLI recupera y guarda un token de acceso en tu máquina. El token caduca después de un tiempo, pero se actualiza automáticamente mientras sigas usándolo.
? How would you like to log in? [Use arrows, Enter to confirm]
> Log in with your browser
Paste an access token
Open this URL in your browser:
https://huggingface.co/oauth/device
And enter the code: ABCD-EFGH
Waiting for authorization...
Token is valid.
The token `oauth-wauplin` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful.También puedes optar por pegar un User Access Token generado desde tu página de Configuración, ya sea de forma interactiva (selecciona Paste an access token) o directamente desde la línea de comandos. Para mayor seguridad, te recomendamos pasar tu token como variable de entorno para evitar pegarlo en el historial de comandos.
# Or using an environment variable
>>> hf auth login --token $HF_TOKEN --add-to-git-credential
Token is valid (permission: write).
The token `token_name` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved in your configured git credential helpers (store).
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful
The current active token is: `token_name`Cuando se ejecuta por un agente de IA (detectado automáticamente, o con --format agent), el comando nunca solicita confirmación: ejecuta el flujo del navegador e imprime instrucciones en texto plano que el agente puede transmitir a su usuario, y luego espera la autorización:
>>> hf auth login --format agent
Ask the user to open https://huggingface.co/oauth/device in a browser and enter the code ABCD-EFGH. The code expires in 900 seconds. Waiting for authorization...
Login successful: logged in as wauplin (token saved as 'oauth-wauplin').hf auth login es interactivo, por lo que --format json y --format quiet no están soportados: usa --token para inicios de sesión no interactivos o automatizados.
Para más detalles sobre la autenticación, consulte esta sección.
hf auth whoami
Si quieres saber si has iniciado sesión, puedes usar hf auth whoami. Este comando no tiene opciones y simplemente imprime tu nombre de usuario y las organizaciones de las que eres miembro en el Hub:
hf auth whoami
Wauplin
orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolClusterSi no has iniciado sesión, se mostrará un mensaje de error.
hf auth logout
Este comando cierra tu sesión. En la práctica, eliminará todos los tokens almacenados en tu máquina. Si deseas eliminar un token específico, puedes especificar el nombre del token como argumento.
Este comando no cerrará tu sesión si has iniciado sesión mediante la variable de entorno HF_TOKEN (ver referencia). Si ese es el caso, debes desestablecer la variable de entorno en la configuración de tu máquina.
hf download
Use el comando hf download para descargar archivos directamente desde el Hub. Internamente, utiliza los mismos helpers hf_hub_download() y snapshot_download() descritos en la guía Download e imprime la ruta devuelta en la terminal. En los ejemplos a continuación, repasaremos los casos de uso más comunes. Para ver la lista completa de opciones disponibles, puede ejecutar:
hf download --helpDescargar un solo archivo
Para descargar un archivo individual de un repositorio, simplemente proporcione el repo_id y el nombre del archivo de la siguiente manera:
>>> hf download gpt2 config.json
downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/wauplin/.cache/huggingface/hub/tmpwrq8dm5o
(…)ingface.co/gpt2/resolve/main/config.json: 100%|██████████████████████████████████| 665/665 [00:00<00:00, 2.49MB/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.jsonEl comando siempre imprimirá en la última línea la ruta del archivo en tu máquina local.
Para descargar un archivo ubicado en un subdirectorio del repositorio, debe proporcionar la ruta del archivo en el repositorio en formato posix, de la siguiente manera:
>>> hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensorsDescargar un repositorio completo
En algunos casos, solo se desea descargar todos los archivos de un repositorio. Esto se puede hacer simplemente especificando el id del repositorio:
>>> hf download HuggingFaceH4/zephyr-7b-beta
Fetching 23 files: 0%| | 0/23 [00:00<?, ?it/s]
...
...
/home/wauplin/.cache/huggingface/hub/models--HuggingFaceH4--zephyr-7b-beta/snapshots/3bac358730f8806e5c3dc7c7e19eb36e045bf720Descargar varios archivos
También puedes descargar un subconjunto de los archivos de un repositorio con un solo comando. Esto se puede hacer de dos maneras. Si ya tienes una lista precisa de los archivos que deseas descargar, simplemente puedes proporcionarlos de forma secuencial:
>>> hf download gpt2 config.json model.safetensors
Fetching 2 files: 0%| | 0/2 [00:00<?, ?it/s]
downloading https://huggingface.co/gpt2/resolve/11c5a3d5811f50298f278a704980280950aedb10/model.safetensors to /home/wauplin/.cache/huggingface/hub/tmpdachpl3o
(…)8f278a7049802950aedb10/model.safetensors: 100%|██████████████████████████████| 8.09k/8.09k [00:00<00:00, 40.5MB/s]
Fetching 2 files: 100%|████████████████████████████████████████████████████████████████| 2/2 [00:00<00:00, 3.76it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10El otro enfoque consiste en proporcionar patrones para filtrar los archivos que desea descargar usando --include y --exclude. Por ejemplo, si desea descargar todos los archivos safetensors de stabilityai/stable-diffusion-xl-base-1.0, excepto los archivos en precisión FP16:
>>> hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"*
Fetching 8 files: 0%| | 0/8 [00:00<?, ?it/s]
...
...
Fetching 8 files: 100%|█████████████████████████████████████████████████████████████████████████| 8/8 (...)
/home/wauplin/.cache/huggingface/hub/models--stabilityai--stable-diffusion-xl-base-1.0/snapshots/462165984030d82259a11f4367a4eed129e94a7bDescarga un conjunto de datos, un Space o un kernel
Los ejemplos anteriores muestran cómo descargar desde un repositorio de modelos. Para descargar un conjunto de datos, un Space o un kernel, use la opción --repo-type:
# https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k
>>> hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
# https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat
>>> hf download HuggingFaceH4/zephyr-chat --repo-type space
...Descargar una revisión específica
Los ejemplos anteriores muestran cómo descargar desde el último commit de la rama principal. Para descargar desde una revisión específica (hash de commit, nombre de rama o etiqueta), use la opción --revision:
>>> hf download bigcode/the-stack --repo-type dataset --revision v1.1
...Usar una URI hf://
En lugar de pasar el tipo de repositorio, la revisión y la ruta del archivo como argumentos y opciones separados, puede proporcionar un único URI hf://. El URI codifica todo a la vez, siguiendo la gramática hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (consulte la referencia de URIs de HF para la sintaxis completa):
# Equivalent to: hf download bigcode/the-stack --repo-type dataset --revision v1.1
>>> hf download hf://datasets/bigcode/the-stack@v1.1
# Download a single file from a specific revision
>>> hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquet
# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/HuggingFaceM4/FineVision/art/
# A bare id still works and defaults to a model repo
>>> hf download hf://openai-community/gpt2/config.jsonCuando se proporciona una URI, --repo-type y --revision tampoco pueden establecerse, ya que ya forman parte de la URI (de lo contrario, se genera un error), y una ruta de archivo incrustada en la URI no puede combinarse con nombres de archivos posicionales. Una barra final / en la ruta denota un subdirectorio (igual que con el argumento posicional). Los nombres de rama que contienen una / deben codificarse en la URL como %2F (p. ej. hf://my-org/my-model@feature%2Ffoo).
Descargar en una carpeta local
La forma recomendada (y predeterminada) de descargar archivos del Hub es utilizar el sistema de caché. Sin embargo, en algunos casos se desea descargar archivos y moverlos a una carpeta específica. Esto es útil para obtener un flujo de trabajo más cercano al que ofrecen los comandos de git. Puedes hacerlo utilizando la opción --local-dir.
Se crea una carpeta .cache/huggingface/ en la raíz de tu directorio local que contiene metadatos sobre los archivos descargados. Esto evita volver a descargar archivos si ya están actualizados. Si los metadatos han cambiado, se descarga la nueva versión del archivo. Esto hace que local-dir esté optimizado para obtener solo los cambios más recientes.
Para más detalles sobre cómo funciona la descarga a un archivo local, consulte la guía de download.
>>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu
...
fuyu/model-00001-of-00002.safetensorsModo de simulación
En algunos casos, es posible que desee verificar qué archivos se descargarían antes de realizar la descarga. Puede comprobarlo utilizando el parámetro --dry-run. Este parámetro enumera todos los archivos a descargar en el repositorio y verifica si ya están descargados o no. Esto proporciona una idea de cuántos archivos deben descargarse y de sus tamaños.
>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00, 6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File Bytes to download
--------------------------------- -----------------
.gitattributes -
64-8bits.tflite 125.2M
64-fp16.tflite 248.3M
64.tflite 495.8M
README.md -
config.json -
flax_model.msgpack 497.8M
generation_config.json -
merges.txt -
model.safetensors 548.1M
onnx/config.json -
onnx/decoder_model.onnx 653.7M
onnx/decoder_model_merged.onnx 655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json -
onnx/merges.txt -
onnx/special_tokens_map.json -
onnx/tokenizer.json -
onnx/tokenizer_config.json -
onnx/vocab.json -
pytorch_model.bin 548.1M
rust_model.ot 702.5M
tf_model.h5 497.9M
tokenizer.json -
tokenizer_config.json -
vocab.json -Para más detalles, consulta la guía de descarga.
Especificar el directorio de caché
Si no se usa --local-dir, todos los archivos se descargan por defecto en el directorio de caché definido por la variable de entorno HF_HOME. Puede especificar una caché personalizada con --cache-dir:
>>> hf download adept/fuyu-8b --cache-dir ./path/to/cache
...
./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745Especificar un token
Para acceder a repositorios privados o con acceso restringido, debe usar un token. De forma predeterminada, se utilizará el token guardado localmente (mediante hf auth login). Si desea autenticarse de forma explícita, use la opción --token:
>>> hf download gpt2 config.json --token=hf_****
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.jsonModo silencioso
Por defecto, el comando hf download es detallado. Imprime información como mensajes de advertencia, detalles sobre los archivos descargados y barras de progreso. Si deseas silenciar todo esto, usa la opción --quiet. Solo se imprime la última línea (es decir, la ruta de los archivos descargados). Esto puede resultar útil si deseas pasar la salida a otro comando en un script.
>>> hf download gpt2 --quiet
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10Tiempo de espera de descarga
En máquinas con conexiones lentas, es posible que se encuentren con problemas de tiempo de espera como este:
`httpx2.TimeoutException: (TimeoutException("HTTPSConnectionPool(host='cdn-lfs-us-1.huggingface.co', port=443): Read timed out. (read timeout=10)"), '(Request ID: a33d910c-84c6-4514-8362-c705e2039d38)')`Para mitigar este problema, puedes establecer la variable de entorno HF_HUB_DOWNLOAD_TIMEOUT en un valor más alto (el valor predeterminado es 10):
export HF_HUB_DOWNLOAD_TIMEOUT=30Para más detalles, consulta la referencia de variables de entorno. Y vuelve a ejecutar tu comando de descarga.
hf upload
Use el comando hf upload para subir archivos directamente al Hub. Internamente, utiliza los mismos helpers upload_file() y upload_folder() descritos en la guía Upload. En los ejemplos a continuación, repasaremos los casos de uso más comunes. Para obtener la lista completa de opciones disponibles, puede ejecutar:
>>> hf upload --helpSubir una carpeta completa
El uso predeterminado de este comando es:
# Usage: hf upload [repo_id] [local_path] [path_in_repo]Para subir el directorio actual en la raíz del repositorio, use:
>>> hf upload my-cool-model . .
https://huggingface.co/Wauplin/my-cool-model/tree/main/Si el repositorio aún no existe, se creará automáticamente.
También puedes subir una carpeta específica:
>>> hf upload my-cool-model ./models .
https://huggingface.co/Wauplin/my-cool-model/tree/main/Por último, puedes subir una carpeta a un destino específico en el repositorio:
>>> hf upload my-cool-model ./path/to/curated/data /data/train
https://huggingface.co/Wauplin/my-cool-model/tree/main/data/trainSubir un solo archivo
También puedes subir un archivo individual configurando local_path para que apunte a un archivo en tu máquina. En ese caso, path_in_repo es opcional y se establecerá de forma predeterminada con el nombre de tu archivo local:
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensorsSi deseas subir un solo archivo a un directorio específico, configura path_in_repo en consecuencia:
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensorsSubir varios archivos
Para subir varios archivos de una carpeta a la vez sin subir la carpeta completa, utiliza los patrones --include y --exclude. También se puede combinar con la opción --delete para eliminar archivos del repositorio mientras se suben nuevos. En el ejemplo siguiente, sincronizamos el Space local eliminando los archivos remotos y subiendo todos los archivos excepto los de /logs:
# Sync local Space with Hub (upload new files except from logs/, delete removed files)
>>> hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
...Subir a un conjunto de datos o Space
Para subir a un conjunto de datos o un Space, use la opción --repo-type:
>>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset
...Subir a una organización
Para subir contenido a un repositorio propiedad de una organización en lugar de un repositorio personal, debes especificarlo explícitamente en repo_id:
>>> hf upload MyCoolOrganization/my-cool-model . .
https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/Subir a una revisión específica
Por defecto, los archivos se suben a la rama main. Si desea subir archivos a otra rama o referencia, use la opción --revision:
# Upload files to a PR
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...Nota: si revision no existe y --create-pr no está configurado, se creará automáticamente una rama a partir de la rama main.
Usar una URI hf://
Al igual que con hf download, el destino se puede expresar como un único URI hf:// que sigue la gramática hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (consulte la referencia de URIs de HF para la sintaxis completa). El tipo de repositorio, la revisión y path_in_repo se leen todos del URI:
# Equivalent to: hf upload Wauplin/my-cool-dataset ./train.csv data/train.csv --repo-type dataset --revision my-branch
>>> hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csv
# Upload a whole folder to the root of a model repo
>>> hf upload hf://Wauplin/my-cool-model ./modelsCuando se proporciona una URI, --repo-type y --revision tampoco pueden establecerse, ya que ya forman parte de la URI (de lo contrario, se genera un error), y una ruta incrustada en la URI no puede combinarse con el argumento path_in_repo.
Subir y crear una PR
Si no tienes permiso para enviar cambios a un repositorio, debes abrir un PR y comunicar a los autores los cambios que deseas realizar. Esto se puede hacer configurando la opción --create-pr:
# Create a PR and upload the files to it
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/Subir a intervalos regulares
En algunos casos, es posible que desee enviar actualizaciones periódicas a un repositorio. Por ejemplo, esto es útil si está entrenando un modelo y desea cargar la carpeta de registros cada 10 minutos. Puede hacer esto usando la opción --every:
# Upload new logs every 10 minutes
hf upload training-model logs/ --every=10Especificar un mensaje de commit
Usa --commit-message y --commit-description para establecer un mensaje y una descripción personalizados para tu commit en lugar de los predeterminados
>>> hf upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%. Check tensorboard for more details."
...
https://huggingface.co/Wauplin/my-cool-model/tree/mainEspecificar un token
Para subir archivos, debe usar un token. De forma predeterminada, se utilizará el token guardado localmente (mediante hf auth login). Si desea autenticarse de forma explícita, use la opción --token:
>>> hf upload Wauplin/my-cool-model ./models . --token=hf_****
...
https://huggingface.co/Wauplin/my-cool-model/tree/mainModo silencioso
Por defecto, el comando hf upload es detallado. Imprime información como mensajes de advertencia, detalles sobre los archivos subidos y barras de progreso. Si deseas silenciar todo esto, usa la opción --quiet. Solo se imprime la última línea (es decir, la URL de los archivos subidos). Esto puede resultar útil si deseas pasar la salida a otro comando en un script.
>>> hf upload Wauplin/my-cool-model ./models . --quiet
https://huggingface.co/Wauplin/my-cool-model/tree/mainhf buckets
Use hf buckets para gestionar buckets en el Hugging Face Hub. Los buckets proporcionan almacenamiento de objetos similar a S3 en Hugging Face, impulsado por el backend de almacenamiento Xet. A diferencia de los repositorios (que se basan en git y rastrean el historial de archivos), los buckets son contenedores de almacenamiento de objetos remotos diseñados para archivos a gran escala con deduplicación direccionable por contenido. Están diseñados para casos de uso donde se necesita un almacenamiento simple, rápido y mutable, como el almacenamiento de checkpoints de entrenamiento, registros, artefactos intermedios o cualquier colección grande de archivos que no requiera control de versiones. En los ejemplos a continuación, repasaremos los casos de uso más comunes. Para una guía completa, consulte la guía de Buckets.
Crear un bucket
Para crear un nuevo bucket, usa hf buckets create. El bucket se creará bajo tu espacio de nombres de forma predeterminada:
>>> hf buckets create my-bucketTambién puedes crear un bucket privado usando la bandera --private:
>>> hf buckets create my-bucket --privateListar e inspeccionar cubos
Para listar todos tus buckets, usa hf buckets list (o su forma abreviada hf buckets ls). También puedes listar los buckets de una organización específica:
>>> hf buckets list
ID PRIVATE SIZE TOTAL_FILES CREATED_AT
-------------------- ------- ---------- ----------- ----------
username/my-bucket 32 5 2026-02-16
username/checkpoints 117609095 700 2026-02-13
username/logs 321757477 2000 2026-02-13
# Human-readable sizes
>>> hf buckets list -h
ID PRIVATE SIZE TOTAL_FILES CREATED_AT
-------------------- ------- -------- ----------- ----------
username/my-bucket 32 B 5 2026-02-16
username/checkpoints 117.6 MB 700 2026-02-13
username/logs 321.8 MB 2000 2026-02-13
# List buckets in a specific namespace
>>> hf buckets ls my-org
# Filter buckets by name
>>> hf buckets list --search "checkpoint"Para obtener información detallada sobre un bucket específico (devuelta como JSON), use hf buckets info:
>>> hf buckets info username/my-bucket
{
"id": "username/my-bucket",
"private": false,
"created_at": "2026-02-16T15:28:32+00:00",
"size": 32,
"total_files": 5
}Cambiar la visibilidad del bucket
Para cambiar un bucket entre privado y público, use hf buckets settings:
# Make a bucket private
>>> hf buckets settings username/my-bucket --private
# Make it public again
>>> hf buckets settings username/my-bucket --publicEliminar un bucket
Para eliminar un bucket, usa hf buckets delete. Se te pedirá confirmación a menos que pases --yes:
>>> hf buckets delete username/my-bucket --yesEliminar archivos
Use hf buckets remove (o su forma abreviada hf buckets rm) para eliminar archivos de un bucket.
Para eliminar un archivo individual, especifique su ruta:
>>> hf buckets rm username/my-bucket/old-model.binPara eliminar todos los archivos bajo un prefijo, use --recursive:
>>> hf buckets rm username/my-bucket/logs/ --recursiveTambién puede apuntar a todos los archivos de un bucket sin prefijo:
>>> hf buckets rm username/my-bucket --recursive --include "*.tmp"Use --dry-run para previsualizar lo que se eliminaría sin borrar nada en realidad:
>>> hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-runExplorar archivos
Use hf buckets list con un ID de bucket para listar los archivos en un bucket:
>>> hf buckets list username/my-bucket
2048 2026-01-15 10:30:00 big.bin
5 2026-01-15 10:30:00 file.txt
2026-01-15 10:30:00 sub/Añade -R para un listado recursivo y -h para tamaños de archivo legibles y fechas cortas. También puedes mostrar una vista de árbol ASCII con --tree, o usar --tree --quiet para un árbol limpio sin metadatos:
# Recursive with human-readable sizes
>>> hf buckets list username/my-bucket -R -h
2.0 KB Jan 15 10:30 big.bin
5 B Jan 15 10:30 file.txt
14 B Jan 15 10:30 sub/nested.txt
4 B Jan 15 10:30 sub/deep/file.txt
# Tree with human-readable sizes
>>> hf buckets list username/my-bucket --tree -h -R
2.0 KB Jan 15 10:30 ├── big.bin
5 B Jan 15 10:30 ├── file.txt
└── sub/
├── deep/
4 B Jan 15 10:30 │ └── file.txt
14 B Jan 15 10:30 └── nested.txt
# Clean tree without metadata
>>> hf buckets list username/my-bucket --tree --quiet -R
├── big.bin
├── file.txt
└── sub/
├── deep/
│ └── file.txt
└── nested.txtPara filtrar por prefijo, agregue el prefijo a la ruta del bucket:
>>> hf buckets list username/my-bucket/sub -RCopiar archivos
Use hf cp para copiar un archivo individual entre su máquina local, los repositorios y los buckets. El origen y el destino pueden ser, cada uno, una ruta local, un URI hf:// (repositorio o bucket) o - (stdin/stdout).
hf cptambién se expone comohf repos cpyhf buckets cp: los tres son exactamente el mismo comando. Utiliza el que mejor se adapte a tu flujo de trabajo.
Para subir un archivo (local → repositorio o bucket):
# To a repository
>>> hf cp ./model.safetensors hf://username/my-model/model.safetensors
# To a bucket (uses the local filename when the destination ends with /)
>>> hf cp ./data.csv hf://buckets/username/my-bucket/logs/Para descargar un archivo (repositorio o bucket → local):
# From a repository
>>> hf cp hf://datasets/username/my-dataset@refs/pr/1/data.csv ./data.csv
# From a bucket, to the current directory (destination omitted)
>>> hf cp hf://buckets/username/my-bucket/config.jsonTambién puede transmitir a stdout o desde stdin usando -:
# Download to stdout
>>> hf cp hf://buckets/username/my-bucket/config.json - | jq .
# Upload from stdin
>>> echo "hello" | hf cp - hf://username/my-model/hello.txtPara copiar entre dos ubicaciones en el Hub (repo/bucket → repo/bucket):
# Repo to repo
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json
# Repo to bucket
>>> hf cp hf://datasets/username/my-dataset/data/train/ hf://buckets/username/my-bucket/datasets/train/
# Bucket to bucket
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/archive-bucket/logs/Al copiar carpetas entre dos ubicaciones del Hub, una barra final / en la ruta de origen controla si se anida la propia carpeta o si solo se copian sus contenidos (estilo rsync):
# Without trailing slash: "logs" dir is nested => archive/logs/...
>>> hf cp hf://buckets/username/my-bucket/logs hf://buckets/username/archive-bucket/
# With trailing slash: only contents of "logs" are copied => archive/...
>>> hf cp hf://buckets/username/my-bucket/logs/ hf://buckets/username/archive-bucket/Notas:
hf cpcopia un solo archivo cuando se involucra una ruta local. Para copiar directorios completos a/desde local, usehf upload/hf download(repos) ohf buckets sync(buckets).- La copia de un bucket a un repositorio aún no está admitida.
- La copia local a local no está admitida (use
cpde su shell). - Las copias entre dos ubicaciones del Hub solo funcionan dentro de la misma región de almacenamiento.
Sincronizar directorios
Use hf buckets sync para sincronizar directorios entre su máquina local y un bucket. Compara el origen y el destino y transfiere solo los archivos modificados.
Para subir un directorio local a un bucket:
>>> hf buckets sync ./data hf://buckets/username/my-bucketPara descargar de un bucket a un directorio local:
>>> hf buckets sync hf://buckets/username/my-bucket ./dataUse --delete para eliminar los archivos de destino que no están presentes en el origen:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --deletePuedes filtrar qué archivos sincronizar usando los patrones --include y --exclude:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"Para actualizar solo los archivos existentes (omitir los nuevos), use --existing. Para crear solo archivos nuevos (omitir los existentes), use --ignore-existing:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --existing
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existingPara mayor seguridad, puedes generar un plan para su revisión antes de ejecutarlo y luego aplicarlo:
# Generate a plan
>>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl
# Review and apply the plan
>>> hf buckets sync --apply sync-plan.jsonlUse --dry-run para imprimir el plan de sincronización como JSONL en stdout sin ejecutar nada. Esto es útil para enviarlo a jq u otras herramientas:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq .
hf synces un alias de nivel superior conveniente parahf buckets sync. Consulte la guía de Buckets para obtener todos los detalles sobre las opciones de sincronización.
hf models
Use hf models para listar los modelos en el Hub y obtener información detallada sobre un modelo específico.
Listar modelos
# List trending models
>>> hf models ls
# Search for models
>>> hf models ls --search "lora"
# Filter by author
>>> hf models ls --author Qwen
# Filter by pipeline tag
>>> hf models ls --pipeline-tag summarization
# Filter by parameter count
>>> hf models ls --num-parameters min:6B,max:128B
# Only non-gated models
>>> hf models ls --no-gated --author google
# Only models runnable by a given app
>>> hf models ls --apps llama.cpp
# Sort by downloads
>>> hf models ls --sort downloads --limit 10Cuando se llama con un ID de modelo, hf models ls lista los archivos en ese repositorio de modelo:
# List files in a model repo
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct
# List files recursively
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct -R
# Tree view with human-readable sizes
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct --tree -h
# List files at a specific revision
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct --revision mainObtener información del modelo
>>> hf models info Lightricks/LTX-2Use --expand para obtener propiedades adicionales como downloads, likes, tags, etc.
Obtener la tarjeta del modelo
Use hf models card para obtener la tarjeta del modelo (README) de un modelo. De forma predeterminada, imprime el contenido completo de la tarjeta en stdout.
# Full card (metadata + text)
>>> hf models card google/gemma-4-31B-it
# Just the metadata (from the YAML frontmatter)
>>> hf models card google/gemma-4-31B-it --metadata
# Metadata as JSON (useful for scripting and agents)
>>> hf models card google/gemma-4-31B-it --metadata --format json
# Just the text body (no YAML frontmatter)
>>> hf models card google/gemma-4-31B-it --texthf datasets
Use hf datasets para listar los datasets en el Hub y obtener información detallada sobre un dataset específico.
Listar conjuntos de datos
# List trending datasets
>>> hf datasets ls
# Search for datasets
>>> hf datasets ls --search "code"
# List official benchmark datasets
>>> hf datasets ls --filter benchmark:official
# Sort by downloads
>>> hf datasets ls --sort downloads --limit 10Cuando se llama con un ID de conjunto de datos, hf datasets ls lista los archivos en ese repositorio de datos:
# List files in a dataset repo
>>> hf datasets ls HuggingFaceFW/fineweb
# List files recursively with human-readable sizes
>>> hf datasets ls HuggingFaceFW/fineweb -R -h
# Tree view
>>> hf datasets ls HuggingFaceFW/fineweb --treeListar un tablero de clasificación de conjuntos de datos
Usa hf datasets leaderboard para mostrar las puntuaciones de los modelos enviados a un conjunto de datos de referencia, de modo que puedas encontrar los mejores modelos para una tarea o comparar modelos según sus puntuaciones en el benchmark.
>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified
>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5 --format jsonObtener información del conjunto de datos
>>> hf datasets info HuggingFaceFW/finewebObtener la tarjeta del conjunto de datos
Use hf datasets card para obtener la tarjeta del dataset (README) de un dataset. De forma predeterminada, imprime el contenido completo de la tarjeta en stdout.
# Full card (metadata + text)
>>> hf datasets card HuggingFaceFW/fineweb
# Just the metadata (from the YAML frontmatter)
>>> hf datasets card HuggingFaceFW/fineweb --metadata
# Metadata as JSON (useful for scripting and agents)
>>> hf datasets card HuggingFaceFW/fineweb --metadata --format json
# Just the text body (no YAML frontmatter)
>>> hf datasets card HuggingFaceFW/fineweb --textListar las URL de parquet
Use hf datasets parquet para descubrir las URLs de los archivos parquet de un conjunto de datos antes de escribir consultas SQL.
Los conjuntos de datos en el Hub se convierten automáticamente a Parquet en el backend mediante el servicio Dataset Viewer (para los conjuntos de datos elegibles).
Consulte la guía de conversión a Parquet para obtener más detalles.
>>> hf datasets parquet cfahlgren1/hub-stats
>>> hf datasets parquet cfahlgren1/hub-stats --subset models
>>> hf datasets parquet cfahlgren1/hub-stats --split train
>>> hf datasets parquet cfahlgren1/hub-stats --format jsonLa salida de tabla predeterminada incluye el subconjunto, la división y la URL del archivo parquet de la API de Hub.
Ejecutar SQL en el parquet del conjunto de datos
Use hf datasets sql para ejecutar consultas SQL en bruto con DuckDB sobre las URLs de parquet de un dataset.
Descubra primero las URLs con hf datasets parquet y luego consulte directamente con read_parquet(...).
>>> hf datasets sql "SELECT COUNT(*) AS rows FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet')"
>>> hf datasets sql "SELECT * FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet') LIMIT 5" --format jsonInstale DuckDB primero si es necesario:
# Python package
>>> pip install duckdb
# or standalone DuckDB CLI (Homebrew: macOS/Linux)
>>> brew install duckdbhf spaces
Use hf spaces para listar los Spaces en el Hub y obtener información detallada sobre un Space específico.
Listar espacios
# List trending Spaces
>>> hf spaces ls
# Search for Spaces
>>> hf spaces ls --search "3d"
# Sort by likes
>>> hf spaces ls --sort likes --limit 10Cuando se llama con un ID de Space, hf spaces ls lista los archivos en ese repositorio de Space:
# List files in a Space repo
>>> hf spaces ls victor/deepsite
# List files recursively with tree view
>>> hf spaces ls victor/deepsite --tree -R -hObtener información del Space
>>> hf spaces info victor/deepsiteObtener tarjeta de Space
Use hf spaces card para obtener la tarjeta (README) de un Space. De forma predeterminada, imprime el contenido completo de la tarjeta en stdout.
# Full card (metadata + text)
>>> hf spaces card mteb/leaderboard
# Just the card metadata (from the YAML frontmatter)
>>> hf spaces card mteb/leaderboard --metadata
# Card metadata as JSON
>>> hf spaces card mteb/leaderboard --metadata --format json
# Just the text body (no YAML frontmatter)
>>> hf spaces card mteb/leaderboard --textPausar o reiniciar un Space desmonta su contenedor, por lo que todo lo escrito en el sistema de archivos efímero se pierde. Para persistir los datos entre reinicios, monta un Volume o bucket con
hf spaces volumes set(ejecutahf spaces volumes --helppara más detalles).
Pausar un Space
Usa hf spaces pause para pausar un Space cuando no lo estés usando (el tiempo en pausa no se factura). Reinícialo más tarde con hf spaces restart.
>>> hf spaces pause username/my-spaceReiniciar un Space
Use hf spaces restart para reiniciar un Space. Pasa --factory-reboot para reconstruir el Space desde cero sin usar la caché de compilación.
>>> hf spaces restart username/my-space
>>> hf spaces restart username/my-space --factory-rebootEsperar a un Space
Use hf spaces wait para bloquear hasta que un Space termine de construirse/iniciarse y alcance un estado estable. Sale con código 0 si el Space está en RUNNING, o con un código distinto de cero en caso contrario (p. ej. BUILD_ERROR). Útil para scripts después de un reinicio o un cambio de hardware.
>>> hf spaces wait username/my-space
# With a timeout
>>> hf spaces wait username/my-space --timeout 5m
# Chain with restart
>>> hf spaces restart username/my-space && hf spaces wait username/my-spaceListar el hardware disponible
Use hf spaces hardware para listar todas las opciones de hardware disponibles para Spaces, incluido el precio.
>>> hf spaces hardwareComprueba tu cuota de ZeroGPU
Use hf spaces zero-gpu quota para consultar cuánto de tu cuota de ZeroGPU te queda y cuándo se restablece. Esto es útil para hacer seguimiento de tu uso al llamar a Spaces de ZeroGPU desde scripts, aplicaciones o agentes.
>>> hf spaces zero-gpu quota
✓ ZeroGPU quota (in GPU-seconds)
remaining: 1810
base: 2400
resets_at: 2026-09-30T18:12:03+00:00
overquota_used: 0
>>> hf spaces zero-gpu quota --format json
{"remaining": 1810, "base": 2400, "resets_at": "2026-09-30T18:12:03+00:00", "overquota_used": 0}Si tu cuota está por agotarse, el comando sugiere comprar créditos desde tus configuraciones de facturación para seguir usando ZeroGPU más allá de la cuota diaria (solo para usuarios PRO, Team y Enterprise).
Actualizar la configuración del Space
Use hf spaces settings para actualizar la configuración de un Space.
>>> hf spaces settings username/my-space --sleep-time 3600
>>> hf spaces settings username/my-space --hardware t4-medium--sleep-time: tiempo de inactividad en segundos antes de que el Space entre en suspensión. Use-1para que nunca entre en suspensión. Solo disponible en hardware actualizado (consulte la documentación sobre el tiempo de suspensión de Spaces).--hardware: tipo de hardware (p. ej.cpu-basic,t4-medium,l4x4). Ejecutahf spaces hardwarepara ver todas las opciones.
Gestionar secretos de Space
Use hf spaces secrets ls para listar los secretos de un Space, hf spaces secrets add para añadir o actualizar uno o más secretos y hf spaces secrets delete para eliminar uno. Pasa --secrets-file PATH para cargar secretos desde un archivo de estilo .env. Las claves existentes se sobrescriben.
>>> hf spaces secrets ls username/my-space
>>> hf spaces secrets add username/my-space -s OPENAI_API_KEY=sk-...
>>> hf spaces secrets add username/my-space --secrets-file .env.secrets
>>> hf spaces secrets delete username/my-space OPENAI_API_KEY --yesLos valores secretos son de solo escritura, por lo que
hf spaces secrets lsmuestra las claves, las descripciones y las marcas de tiempo de actualización, pero nunca los valores secretos en sí.
Gestionar variables de entorno de Space
Use hf spaces variables para gestionar variables de entorno no secretas en un Space. A diferencia de los secretos, las variables son legibles, por lo que ls muestra tanto las claves como los valores. Pasa --env-file PATH en add para cargarlas desde un archivo de estilo .env.
>>> hf spaces variables ls username/my-space
>>> hf spaces variables add username/my-space -e MODEL_ID=gpt2 -e MAX_TOKENS=512
>>> hf spaces variables add username/my-space --env-file .env
>>> hf spaces variables delete username/my-space MAX_TOKENS --yesConectarse a un Space mediante SSH (modo de desarrollo)
Use hf spaces ssh para abrir una sesión SSH en el contenedor de Dev Mode de un Space. Si Dev Mode no está habilitado, la CLI le pedirá que lo habilite (o use --auto para omitir la solicitud).
Tu clave pública SSH debe estar registrada en tu configuración. Consulta la documentación de Dev Mode para más detalles.
# SSH into a Space
>>> hf spaces ssh username/my-space
# Print the SSH command without running it
>>> hf spaces ssh username/my-space --dry-run
# Auto-enable Dev Mode if disabled
>>> hf spaces ssh username/my-space --auto
# Use a specific SSH key
>>> hf spaces ssh username/my-space -i ~/.ssh/id_ed25519hf papers
Use hf papers para listar, buscar, obtener información estructurada y leer el contenido en markdown de los papers en el Hub.
Listar artículos
# List most recent daily papers
>>> hf papers ls
# List trending papers
>>> hf papers ls --sort=trending
# List papers from a specific date
>>> hf papers ls --date=2025-01-23
# List today's papers
>>> hf papers ls --date=today
# List papers from a specific week
>>> hf papers ls --week=2025-W09
# List papers from a specific month
>>> hf papers ls --month=2025-02
# List papers submitted by a specific user
>>> hf papers ls --submitter=akhaliq
# Limit results
>>> hf papers ls --sort=trending --limit=5Buscar papers
# Search papers by keyword
>>> hf papers search "vision language"
# Limit search results
>>> hf papers search "diffusion models" --limit=10
# Output as JSON
>>> hf papers search "attention" --format=jsonObtener información del artículo
# Get structured metadata for a paper (returns JSON)
>>> hf papers info 2601.15621Leer el artículo como markdown
# Read the full paper content as markdown
>>> hf papers read 2601.15621discusiones de hf
Usa hf discussions para gestionar discusiones y pull requests en los repositorios de Hub directamente desde tu terminal. Puedes listar, ver, crear, comentar, cerrar, reabrir y fusionar tanto discusiones como PRs. Para una guía completa sobre cómo funcionan las funciones de la comunidad de Hub, consulta la Guía de discusiones y pull requests.
Listar discusiones
Para listar las discusiones y PR abiertas en un repositorio, pase el ID del repositorio a hf discussions list (o su forma abreviada hf discussions ls):
>>> hf discussions list username/my-modelPuedes filtrar los resultados por tipo (discussion o pull_request), estado (open, closed, merged o all) o autor:
>>> hf discussions list username/my-model --kind pull_request --status merged
>>> hf discussions list username/my-model --author alicePara scripts, use --format json para obtener una salida estructurada, o --quiet para imprimir solo los números de discusión (uno por línea):
>>> hf discussions list username/my-model --format json
>>> hf discussions ls username/my-model --quietObtener información sobre una discusión o PR
Para inspeccionar una discusión o PR específica, pasa el ID del repositorio y el número de la discusión:
>>> hf discussions info username/my-model 5La salida contiene los metadatos de la discusión (título, estado, autor, etc.) junto con la lista completa de eventos de la conversación. Para mostrar el diff de una pull request, usa hf discussions diff en su lugar.
Use --format json para una salida legible por máquina y establezca NO_COLOR=1 para eliminar los colores ANSI al enviar la salida a otras herramientas.
Crea una discusión o una PR
Para abrir una nueva discusión, proporciona un título con --title. Puedes incluir opcionalmente una descripción en línea con --body, o cargarla desde un archivo con --body-file:
>>> hf discussions create username/my-model --title "Bug report"
>>> hf discussions create username/my-model --title "Feature request" --body "Please add X"
>>> hf discussions create username/my-model --title "Report" --body-file report.mdPara crear una pull request en lugar de una discusión simple, añade la bandera --pull-request:
>>> hf discussions create username/my-model --title "Fix typo" --pull-requestComentar en una discusión o PR
Agrega un comentario a una discusión o PR existente especificando su número. El cuerpo del comentario se puede pasar de forma inline con --body, leerlo desde un archivo con --body-file o recibirlo desde stdin usando --body-file -:
>>> hf discussions comment username/my-model 5 --body "Thanks for reporting!"
>>> hf discussions comment username/my-model 5 --body-file review.md
>>> echo "LGTM" | hf discussions comment username/my-model 5 --body-file -Editar un comentario
Edit un comentario existente en su lugar pasando el número de la discusión y el ID del comentario. Los IDs de comentario se pueden obtener con hf discussions info:
>>> hf discussions edit username/my-model 5 abc123 --body "Updated comment."
>>> hf discussions edit username/my-model 5 abc123 --body-file fixed.mdAdjuntar imágenes y videos
Pasa --attach a hf discussions create, comment o edit para subir un archivo de imagen, video o audio e incrustarlo en el cuerpo, como cuando arrastras un archivo al cuadro de comentarios en el Hub. Si el cuerpo ya referencia el archivo, como en , la referencia apunta al archivo subido. De lo contrario, el archivo se añade al cuerpo. Para establecer el texto alternativo de una imagen añadida, agrégalo después de un #:
>>> hf discussions create username/my-model --title "Fix rendering" --pr --body "Before: " --attach ./before.png --attach "./after.png#After the fix"
>>> hf discussions comment username/my-model 5 --body "Here is a demo:" --attach demo.mp4Los formatos admitidos son PNG, JPEG, GIF, WebP, MP4, MOV, WebM, MP3 y WAV, con un tamaño máximo de 10 MB (50 MB para videos).
Cerrar, reabrir y fusionar
Puedes cerrar una discusión o PR con hf discussions close. De forma predeterminada, se te pedirá confirmación. Pasa --yes para omitir la solicitud y --comment para dejar un mensaje de cierre:
>>> hf discussions close username/my-model 5
>>> hf discussions close username/my-model 5 --yes --comment "Resolved"Para reabrir una discusión previamente cerrada, use hf discussions reopen:
>>> hf discussions reopen username/my-model 5 --yesPara fusionar una solicitud de extracción, use hf discussions merge:
>>> hf discussions merge username/my-model 5 --yesRenombrar y comparar
Puedes cambiar el nombre de una discusión proporcionando el nuevo título:
>>> hf discussions rename username/my-model 5 "Updated title"Para ver la diferencia de una solicitud de extracción directamente en tu terminal, usa hf discussions diff:
>>> hf discussions diff username/my-model 5hf repos
hf repos permite listar, crear, duplicar, eliminar y mover repositorios, actualizar sus ajustes y eliminar archivos en Hugging Face Hub. También incluye subcomandos para gestionar ramas y etiquetas.
Listar repositorios
Use hf repos ls para listar todos tus repositorios (modelos, conjuntos de datos, espacios y cubos) con información de almacenamiento, ordenados por uso de almacenamiento. De forma predeterminada, solo se muestran los primeros 30 repositorios:
# List all your repos (first 30)
>>> hf repos ls
REPOSITORY TYPE UPDATED VISIBILITY STORAGE % OF TOTAL
------------------------ ------- ---------- ---------- -------- ----------
username/bucket-raw bucket 2026-04-29 public 1.7 TB 72.3%
username/my-model model 2026-05-06 public 4.8 GB 18.1%
username/my-dataset dataset 2024-09-14 private 598.4 MB 5.2%
Hint: Showing 30 of 42 repos. Use `--limit 0` to list all.Filtrar por tipo de repositorio, buscar por nombre o ajustar el límite:
# List only models
>>> hf repos ls --type model
# Search by name
>>> hf repos ls --search "bert"
# List repos from an organization
>>> hf repos ls --namespace my-org
# Combine filters
>>> hf repos ls --namespace my-org --type dataset --search "train"
# List all repos (no limit)
>>> hf repos ls --limit 0Use --format json para scripting o -q solo para IDs. Al usar pipes, use --limit 0 para exportar todos los repositorios:
>>> hf repos ls --limit 0 --format json | jq '.[].id'
>>> hf repos ls -qCrear un repositorio
>>> hf repos create Wauplin/my-cool-model
Successfully created Wauplin/my-cool-model on the Hub.
Your repo is now available at https://huggingface.co/Wauplin/my-cool-modelCrea un conjunto de datos privado o un Space:
>>> hf repos create my-cool-dataset --repo-type dataset --private
>>> hf repos create my-gradio-space --repo-type space --sdk gradioUse --exist-ok si el repositorio ya puede existir, y --resource-group-id para apuntar a un grupo de recursos de Enterprise.
Crea un repositorio en una región específica:
>>> hf repos create my-model --region usDuplicar un repositorio
Use hf repos duplicate para copiar un modelo, conjunto de datos o Space existente a su cuenta (o a una organización). La copia se realiza en el servidor y preserva el historial de git:
>>> hf repos duplicate openai/gdpval --type dataset
>>> hf repos duplicate openai/gdpval myorg/my-gdpval --type dataset --privateLos archivos LFS/Xet del nuevo repositorio pueden seguir copiándose en segundo plano después de que el comando finalice. En ese caso, se imprime una advertencia y la descarga de estos archivos desde el nuevo repositorio puede fallar hasta que la copia se complete.
Eliminar un repositorio
>>> hf repos delete Wauplin/my-cool-modelDatasets y Spaces:
>>> hf repos delete my-cool-dataset --repo-type dataset
>>> hf repos delete my-gradio-space --repo-type spaceMover un repositorio
>>> hf repos move old-namespace/my-model new-namespace/my-modelActualizar la configuración del repositorio
>>> hf repos settings Wauplin/my-cool-model --gated auto
>>> hf repos settings Wauplin/my-cool-model --private true
>>> hf repos settings Wauplin/my-cool-model --private false--gated: uno deauto,manual,false--private true|false: establece la privacidad del repositorio
Eliminar archivos de un repositorio
El subcomando hf repos delete-files <repo_id> permite eliminar archivos de un repositorio. A continuación se muestran algunos ejemplos de uso.
Eliminar una carpeta:
>>> hf repos delete-files Wauplin/my-cool-model folder/
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Eliminar varios archivos:
>>> hf repos delete-files Wauplin/my-cool-model file.txt folder/pytorch_model.bin
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Use patrones comodín para eliminar conjuntos de archivos. Los patrones son comodines estándar (patrones glob) tal como se documenta aquí. La coincidencia de patrones se basa en fnmatch.
Tenga en cuenta que
fnmatchhace coincidir*a través de los límites de ruta, a diferencia del globbing tradicional de la shell de Unix. Por ejemplo,"data/*.json"coincidirá tanto condata/file.jsoncomo condata/subdir/file.json. Para hacer coincidir solo los archivos del directorio inmediato, debe enumerarlos explícitamente o usar patrones más específicos.
>>> hf repos delete-files Wauplin/my-cool-model "*.txt" "folder/*.bin"
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Para eliminar archivos de un repositorio, debe estar autenticado y autorizado. De forma predeterminada, se utilizará el token guardado localmente (mediante hf auth login). Si desea autenticarse de forma explícita, use la opción --token:
>>> hf repos delete-files --token=hf_**** Wauplin/my-cool-model file.txthf repos branch
Use hf repos branch para crear y eliminar ramas de los repositorios en el Hub.
# Create a branch
>>> hf repos branch create Wauplin/my-cool-model dev
# Create a branch from a specific revision
>>> hf repos branch create Wauplin/my-cool-model release-1 --revision refs/pr/104
# Delete a branch
>>> hf repos branch delete Wauplin/my-cool-model devTodos los comandos aceptan
--repo-type(uno demodel,dataset,space) y--tokensi necesitas autenticarte explícitamente. Usa--helpen cualquier comando para ver todas las opciones.
hf cache
Use hf cache para gestionar su directorio de caché local de Hugging Face. La caché almacena los modelos, conjuntos de datos, Spaces y kernels descargados del Hub.
# List cached repositories
>>> hf cache ls
# List cached revisions
>>> hf cache ls --revisions
# Remove specific items from cache
>>> hf cache rm model/gpt2
# Remove unreferenced revisions
>>> hf cache prune
# Verify cached file checksums
>>> hf cache verify gpt2hf cache ls
Use hf cache ls para inspeccionar lo que se almacena localmente en su caché de Hugging Face. Por defecto, agrega la información por repositorio:
>>> hf cache ls
ID SIZE LAST_ACCESSED LAST_MODIFIED REFS
--------------------------- -------- ------------- ------------- -----------
dataset/nyu-mll/glue 157.4M 2 days ago 2 days ago main script
model/LiquidAI/LFM2-VL-1.6B 3.2G 4 days ago 4 days ago main
model/microsoft/UserLM-8b 32.1G 4 days ago 4 days ago main
Found 3 repo(s) for a total of 5 revision(s) and 35.5G on disk.Añade --revisions para profundizar en instantáneas específicas y encadena filtros para centrarte en lo importante:
>>> hf cache ls --filter "size>30g" --revisions
ID REVISION SIZE LAST_MODIFIED REFS
------------------------- ---------------------------------------- -------- ------------- ----
model/microsoft/UserLM-8b be8f2069189bdf443e554c24e488ff3ff6952691 32.1G 4 days ago main
Found 1 repo(s) for a total of 1 revision(s) and 32.1G on disk.El comando admite varios formatos de salida para scripts: --format json imprime objetos estructurados, --format csv escribe filas separadas por comas y --quiet imprime solo los ID. Use --sort para ordenar las entradas por accessed, modified, name o size (añada :asc o :desc para controlar el orden) y --limit para limitar los resultados a las N primeras entradas. Combine estas opciones con --cache-dir para apuntar a ubicaciones de caché alternativas. Consulte la guía Manage your cache para flujos de trabajo avanzados.
Elimina las entradas de caché seleccionadas con hf cache ls --q pasando los ID a hf cache rm:
>>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) -y
About to delete 2 repo(s) totalling 5.31G.
- model/meta-llama/Llama-3.2-1B-Instruct (entire repo)
- model/hexgrad/Kokoro-82M (entire repo)
Deleted 2 repo(s) and 2 revision(s); freed 5.31G.hf cache rm
hf cache rm elimina repositorios en caché, revisiones individuales o archivos sueltos. Pasa uno o varios IDs de repositorio (model/bert-base-uncased), URIs hf:// o hashes de revisión:
>>> hf cache rm model/LiquidAI/LFM2-VL-1.6B
About to delete 1 repo(s) totalling 3.2G.
- model/LiquidAI/LFM2-VL-1.6B (entire repo)
Proceed with deletion? [y/N]: y
Deleted 1 repo(s) and 2 revision(s); freed 3.2G.También se admiten URI de nivel de repositorio hf://:
>>> hf cache rm hf://models/openai-community/gpt2 --dry-run
About to delete 1 repo(s) totalling 1.1G.
- model/openai-community/gpt2 (entire repo)
Dry run: no files were deleted.Para eliminar un archivo individual en lugar de un repositorio completo, por ejemplo una cuantización GGUF, pase un URI de archivo hf://. El archivo se elimina de todas las revisiones en caché del repositorio y su blob se elimina solo si ningún otro archivo en caché lo referencia:
>>> hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-run
About to delete 1 file(s) totalling 16.5G.
- model/unsloth/gemma-3-27b-it-GGUF@3f4b5c1d2e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c/gemma-3-27b-it-Q4_K_M.gguf
Dry run: no files were deleted.La revisión sigue siendo utilizable, y un archivo eliminado se vuelve a descargar la próxima vez que se necesite. Las rutas deben coincidir exactamente: no se admiten carpetas ni patrones glob, y los destinos de archivo no pueden mezclarse con repositorios o revisiones en la misma llamada.
Mezcle repositorios y revisiones específicas en la misma llamada. Use --dry-run para previsualizar el impacto, o --yes para omitir el aviso de confirmación, útil en scripts automatizados:
>>> hf cache rm model/t5-small 8f3ad1c --dry-run
About to delete 1 repo(s) and 1 revision(s) totalling 1.1G.
- model/t5-small:
8f3ad1c [main] 1.1G
Dry run: no files were deleted.Al trabajar fuera de la ubicación de caché predeterminada, combine el comando con --cache-dir PATH.
hf cache prune
hf cache prune es un atajo de conveniencia que recupera el espacio ocupado por basura de la caché: todas las revisiones desvinculadas (no referenciadas) (conservando solo las revisiones que aún son alcanzables a través de una rama o etiqueta), cualquier archivo .incomplete residual de descargas interrumpidas y los blobs compartidos que ya no son referenciados por ningún repositorio en caché:
>>> hf cache prune
About to delete 3 unreferenced revision(s) and 2 incomplete download(s) (2.4G total).
- model/t5-small:
1c610f6b [refs/pr/1] 820.1M
d4ec9b72 [(detached)] 640.5M
- dataset/google/fleurs:
2b91c8dd [(detached)] 937.6M
Proceed? [y/N]: y
Deleted 3 unreferenced revision(s) and 2 incomplete download(s); freed 2.4G.Los archivos .incomplete son descargas parciales que quedan cuando una descarga se interrumpe. No se rastrean con hf cache ls/rm (que funcionan a nivel de revisión), por lo que hf cache ls los señala con una pista y hf cache prune los elimina automáticamente.
Al igual que con los otros comandos de caché, --dry-run, --yes y --cache-dir están disponibles. Consulte la guía Gestionar su caché para más ejemplos.
hf cache verify
Use hf cache verify para validar los archivos locales contra sus sumas de verificación en el Hub. Puede verificar una instantánea de la caché o un directorio local regular.
Ejemplos:
# Verify main revision of a model in cache
>>> hf cache verify deepseek-ai/DeepSeek-OCR
# Verify a specific revision
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision refs/pr/5
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision ef93bf4a377c5d5ed9dca78e0bc4ea50b26fe6a4
# Verify a private repo
>>> hf cache verify me/private-model --token hf_***
# Verify a dataset
>>> hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset
# Verify files in a local directory
>>> hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repoPor defecto, el comando emite advertencias sobre archivos faltantes o adicionales. Utilice banderas para convertir estas advertencias en errores:
>>> hf cache verify deepseek-ai/DeepSeek-OCR --fail-on-missing-files --fail-on-extra-filesSi tiene éxito, verá un resumen:
✅ Verified 13 file(s) for 'deepseek-ai/DeepSeek-OCR' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6 All checksums match.
Si se detectan discrepancias, el comando imprime una lista detallada y finaliza con un estado no cero.
hf repos tag
Use hf repos tag para crear, listar y eliminar etiquetas de los repositorios en el Hub.
# Create a tag
>>> hf repos tag create my-model v1.0
# List tags
>>> hf repos tag list my-model
# Delete a tag
>>> hf repos tag delete my-model v1.0Etiquetar un modelo
Para etiquetar un repositorio, debe proporcionar el repo_id y el nombre de la tag:
>>> hf repos tag create Wauplin/my-cool-model v1.0
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-modelEtiquetar un modelo en una revisión específica
Si deseas etiquetar una revisión específica, puedes usar la opción --revision. De forma predeterminada, la etiqueta se creará en la rama main:
>>> hf repos tag create Wauplin/my-cool-model v1.0 --revision refs/pr/104
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-modelEtiquetar un conjunto de datos o un Espacio
Si deseas etiquetar un conjunto de datos o un Space, debes especificar la opción --repo-type:
>>> hf repos tag create bigcode/the-stack v1.0 --repo-type dataset
You are about to create tag v1.0 on dataset bigcode/the-stack
Tag v1.0 created on bigcode/the-stackListar etiquetas
Para listar todas las etiquetas de un repositorio, use el subcomando list (o ls):
>>> hf repos tag list Wauplin/gradio-space-ci --repo-type space
Tags for space Wauplin/gradio-space-ci:
0.2.2
0.2.1
0.2.0
0.1.2
0.0.2
0.0.1Eliminar una etiqueta
Para eliminar una etiqueta, usa el subcomando delete:
>>> hf repos tag delete Wauplin/my-cool-model v1.0
You are about to delete tag v1.0 on model Wauplin/my-cool-model
Proceed? [Y/n] y
Tag v1.0 deleted on Wauplin/my-cool-modelTambién puedes pasar -y para omitir el paso de confirmación.
hf env
El comando hf env imprime detalles sobre la configuración de tu máquina. Esto es útil cuando abres un problema en GitHub para ayudar a los mantenedores a investigar tu problema.
>>> hf env
Copy-and-paste the text below in your GitHub issue.
- huggingface_hub version: 1.0.0.rc6
- Platform: Linux-6.8.0-85-generic-x86_64-with-glibc2.35
- Python version: 3.11.14
- Running in iPython ?: No
- Running in notebook ?: No
- Running in Google Colab ?: No
- Running in Google Colab Enterprise ?: No
- Token path ?: /home/wauplin/.cache/huggingface/token
- Has saved token ?: True
- Who am I ?: Wauplin
- Configured git credential helpers: store
- Installation method: unknown
- Torch: N/A
- httpx2: 2.0.0
- hf_xet: 1.1.10
- gradio: 5.41.1
- tensorboard: N/A
- pydantic: 2.11.7
- ENDPOINT: https://huggingface.co
- HF_HUB_CACHE: /home/wauplin/.cache/huggingface/hub
- HF_ASSETS_CACHE: /home/wauplin/.cache/huggingface/assets
- HF_TOKEN_PATH: /home/wauplin/.cache/huggingface/token
- HF_STORED_TOKENS_PATH: /home/wauplin/.cache/huggingface/stored_tokens
- HF_HUB_OFFLINE: False
- HF_HUB_DISABLE_TELEMETRY: False
- HF_HUB_DISABLE_PROGRESS_BARS: None
- HF_HUB_DISABLE_SYMLINKS_WARNING: False
- HF_HUB_DISABLE_EXPERIMENTAL_WARNING: False
- HF_HUB_DISABLE_IMPLICIT_TOKEN: False
- HF_HUB_DISABLE_XET: False
- HF_HUB_DISABLE_SHARED_BLOBS: False
- HF_HUB_ETAG_TIMEOUT: 10
- HF_HUB_DOWNLOAD_TIMEOUT: 10hf jobs
Ejecuta trabajos de cómputo en la infraestructura de Hugging Face con una interfaz similar a Docker.
hf jobs es una herramienta de línea de comandos que te permite ejecutar cualquier cosa en la infraestructura de Hugging Face (¡incluidas GPUs y TPUs!) con comandos simples. Piensa en docker run, pero para ejecutar código en A100s.
Para una visión general de Jobs y los precios, consulte la documentación de Jobs de Hub. Para el uso de la API de Python junto con la CLI, consulte la guía para ejecutar y gestionar Jobs.
# Directly run Python code
>>> hf jobs run --name hello-world python:3.12 python -c 'print("Hello from the cloud!")'
# Use GPUs without any setup
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c "import torch; print(torch.cuda.get_device_name())"
# Run in an organization account
>>> hf jobs run --namespace my-org-name python:3.12 python -c 'print("Running in an org account")'
# Run from Hugging Face Spaces
>>> hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c 'select "hello world"'
# Run a Python script with `uv` (experimental)
>>> hf jobs uv run --name my-script my_script.pyLos Hugging Face Jobs están disponibles para cualquier usuario u organización con créditos prepagados.
Inicio rápido
1. Ejecuta tu primer trabajo
# Run a simple Python script
>>> hf jobs run python:3.12 python -c 'print("Hello from HF compute!")'Este comando ejecuta el trabajo y muestra los registros. Puedes pasar --detach para ejecutar el Job en segundo plano e imprimir solo el ID del Job. Añade -q para imprimir solo el ID del Job, lo cual es útil para capturarlo en un script:
>>> JOB_ID=$(hf jobs run -dq python:3.12 python train.py)
>>> hf jobs wait "$JOB_ID"2. Verificar el estado del trabajo
# List your running jobs
>>> hf jobs ls
# List all jobs
>>> hf jobs ls -a
# Inspect the status of a job
>>> hf jobs inspect <job_id>
# View logs from a job
>>> hf jobs logs <job_id>
# View resources usage stats and metrics of running jobs
>>> hf jobs stats
# View resources usage stats and metrics of some jobs
>>> hf jobs stats [job_ids]...
# Follow live stats until the jobs complete
>>> hf jobs stats -f [job_ids]...
# Cancel a job
>>> hf jobs cancel <job_id>
# Wait until one or more jobs finish (exit code 0 only if all jobs completed successfully)
>>> hf jobs wait <job_id> [<job_id>...]
# Wait for all currently running jobs
>>> hf jobs ls -q | xargs hf jobs waitLos hf jobs run y hf jobs wait no desvinculados finalizan con un código no cero si un Job falla, por lo que puedes encadenar comandos con &&:
>>> hf jobs run python:3.12 python train.py && echo "training succeeded"3. Ejecutar en GPU
También puede ejecutar trabajos en GPUs o TPUs con la opción --flavor. Por ejemplo, para ejecutar un trabajo de PyTorch en una GPU A10G:
# Use an A10G GPU to check PyTorch CUDA
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'Al ejecutarlo, se mostrará la siguiente salida.
This code ran with the following GPU: NVIDIA A10G
Use -- para separar las opciones de Jobs de los argumentos pasados a su comando o script.
Jobs no interpreta las opciones posteriores a --.
>>> hf jobs run --flavor cpu-basic python:3.12 -- python --help¡Listo! Ahora estás ejecutando código en la infraestructura de Hugging Face.
Casos de uso habituales
- Entrenamiento de modelos: Ajuste fino o entrenamiento de modelos en GPUs (T4, A10G, A100) sin gestionar la infraestructura
- Generación de datos sintéticos: Genera conjuntos de datos a gran escala utilizando LLMs en hardware potente
- Procesamiento de datos: Procesa conjuntos de datos masivos con configuraciones de CPU de alto rendimiento para cargas de trabajo paralelas
- Inferencia por lotes: Ejecuta inferencia sin conexión en miles de muestras usando configuraciones de GPU optimizadas
- Experimentos y benchmarks: Ejecuta experimentos de ML en hardware consistente para obtener resultados reproducibles
- Desarrollo y depuración: Prueba el código de GPU sin configuración local de CUDA
Pasar variables de entorno y secretos
Puedes pasar variables de entorno a tu trabajo usando
# Pass environment variables
>>> hf jobs run -e FOO=foo -e BAR=bar python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'# Pass an environment from a local .env file
>>> hf jobs run --env-file .env python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'# Pass secrets by name - the value is read from your environment, never from the command line
>>> hf jobs run -s MY_SECRET python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'# Pass secrets from a local .env.secrets file - they will be encrypted server side
>>> hf jobs run --secrets-file .env.secrets python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'# Or pipe them in, so the values touch neither the command line nor the disk
>>> printf 'MY_SECRET=psswrd\n' | hf jobs run --secrets-file - python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'Los secretos se cifran en el servidor en las tres formas. -s MY_SECRET=psswrd también funciona, pero el valor termina en el historial de tu shell y en la lista de procesos (/proc/<pid>/cmdline en Linux), por lo que la CLI imprime una advertencia en stderr cuando lo usas; reserva esa forma para valores que no son realmente sensibles. Lo mismo aplica a --token <value>: prefiere hf auth login o la variable de entorno HF_TOKEN. Un archivo de entorno o secretos debe ser legible solo por ti (chmod 600); la CLI emite una advertencia si no lo es.
Use
--secrets HF_TOKENpara pasar su token local de Hugging Face de forma implícita. Con esta sintaxis, el secreto se recupera de la variable de entorno. En el caso deHF_TOKEN, puede leer el archivo de token ubicado en la carpeta de inicio de Hugging Face si la variable de entorno no está definida.
Variables de entorno integradas
Dentro del contenedor del trabajo, las siguientes variables de entorno están disponibles automáticamente:
| Variable | Descripción |
|---|---|
JOB_ID | El identificador único del trabajo actual. Úselo para hacer referencia al trabajo de forma programática. |
ACCELERATOR | El tipo de acelerador disponible (p. ej., t4-medium, a10g-small, a100x4). Vacío si no hay acelerador. |
CPU_CORES | El número de núcleos de CPU disponibles para el trabajo (p. ej., 2, 4, 8). |
MEMORY | La cantidad de memoria disponible para el trabajo (p. ej., 16Gi, 32Gi). |
# Access job environment information
>>> hf jobs run python:3.12 python -c "import os; print(f'Job: {os.environ.get(\"JOB_ID\")}, CPU: {os.environ.get(\"CPU_CORES\")}, Mem: {os.environ.get(\"MEMORY\")}')"Tiempo de espera del trabajo
Los trabajos tienen un tiempo de espera predeterminado de 30 minutos, tras el cual se detienen automáticamente. Para tareas de larga duración, como el entrenamiento de modelos, configura un tiempo de espera personalizado usando la opción --timeout:
# Set timeout in seconds (default unit)
>>> hf jobs run --timeout 7200 python:3.12 python train.py
# Use time units: s (seconds), m (minutes), h (hours), d (days)
>>> hf jobs run --timeout 2h pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel python train.py
>>> hf jobs run --timeout 90m python:3.12 python process_data.py
>>> hf jobs run --timeout 1.5h python:3.12 python train.py # floats are supportedLa opción --timeout también funciona con scripts de UV y trabajos programados:
# UV script with timeout
>>> hf jobs uv run --timeout 2h training_script.py
# Scheduled job with timeout
>>> hf jobs scheduled run @daily --timeout 4h python:3.12 python daily_task.pySi tu trabajo supera el tiempo de espera, se terminará automáticamente. Configura siempre un tiempo de espera adecuado con un margen de seguridad para tareas de larga duración y evitar terminaciones inesperadas del trabajo.
Reintentar y volver a ejecutar un Job
--attempts establece el número máximo de intentos, incluida la primera ejecución. Funciona con Docker, UV y Jobs programados. Volver a ejecutar un Job inicia un nuevo Job con la misma especificación guardada:
>>> hf jobs run --attempts 3 --detach python:3.12 python train.py
>>> hf jobs rerun <job_id>Un número de intentos de 3 permite hasta dos reintentos cuando un Job falla. hf jobs rerun también reutiliza el número de intentos original. Al igual que hf jobs run, transmite los registros del nuevo Job hasta que termina. Use --detach para regresar de inmediato.
Hardware
Opciones disponibles de --flavor:
- CPU:
cpu-basic,cpu-upgrade - GPU:
t4-small,t4-medium,l4x1,l4x4,a10g-small,a10g-large,a10g-largex2,a10g-largex4,a100-large - TPU:
v5e-1x1,v5e-2x2,v5e-2x4
(actualizado en 07/2025 a partir de la documentación de suggested_hardware de Hugging Face)
Volúmenes
Monta un volumen en el disco del Job usando -v o --volume.
Puedes montar cualquier Repositorio de Hugging Face (modelo/conjunto de datos/espacio) o Storage Bucket utilizando el esquema de URL hf://. Por ejemplo:
- montar un repositorio de modelos:
-v hf://openai/gpt-oss-120b:/model - montar un repositorio de datos:
-v hf://datasets/HuggingFaceFW/fineweb:/data - montar un bucket de almacenamiento:
-v hf://buckets/username/my-bucket:/mnt - montar un espacio:
-v hf://spaces/username/my-space:/app - montar una subcarpeta dentro de un repositorio:
-v hf://datasets/org/ds/train:/data
Luego, puede usar el volumen montado como un directorio local:
# Docker Job with a mounted volume as input
>>> hf jobs run -v hf://datasets/HuggingFaceFW/fineweb:/dataset \
... duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5"
# UV Job with a mounted volume to save checkpoints when training a model
>>> hf jobs uv run -v hf://buckets/username/my-bucket:/training-outputs \
... sft.py --output-dir /training-outputs/training-v3-final ...Los modelos, conjuntos de datos y espacios siempre se montan en solo lectura. Los cubos de almacenamiento son de lectura y escritura por defecto, lo cual resulta especialmente útil para datos que cambian con frecuencia, ya que los archivos pueden sobrescribirse o eliminarse en su ubicación original.
Use :ro para habilitar solo lectura:
- montar un bucket de almacenamiento en solo lectura:
-v hf://buckets/username/my-bucket:/mnt:ro
Montar datos locales
El lado de origen de -v también puede ser un directorio local. Primero se sincroniza con tu jobs-artifacts Storage Bucket y la carpeta de bucket resultante se monta en el Job:
>>> hf jobs uv run -v ./my-data:/data process.pyAl volver a ejecutar el comando, solo se suben los archivos nuevos o modificados. Los directorios locales se montan en solo lectura de forma predeterminada. Use :rw para permitir que el Job escriba en el volumen, por ejemplo, para recuperar las salidas después de que el Job se complete (también funciona un directorio local vacío):
>>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py
...
Hint: Volume '/output' is mounted read-write. Once the job is over, pull back its data with:
hf buckets sync hf://buckets/username/jobs-artifacts/md-out-a1b2c3d4 ./md-outEtiquetas
Añade etiquetas a un Job usando -l o --label. Las etiquetas son pares clave=valor que aplican metadatos a un Job. Para etiquetar un Job con dos etiquetas, repite la bandera de etiqueta (-l o --label):
>>> hf jobs run -l my-label --label foo=bar ubuntu echo "This Job has multiple labels"La clave my-label no especifica un valor, por lo que su valor predeterminado es una cadena vacía ("").
Use --name para añadir la etiqueta name al crear un Job. Los nombres facilitan encontrar e identificar los Jobs en la interfaz; son opcionales y no tienen que ser únicos. Si no pasas --name, se deriva un nombre automáticamente a partir de la imagen de Docker o del script, más un hash corto del comando y de la configuración de tiempo de ejecución resuelta (flavor, timeout, valores de entorno, …), de modo que la misma configuración siempre produce el mismo nombre (p. ej. python:3.12 foo --truc → python-3-12-1a2b3c4d). Cambiar una configuración cambia el nombre, incluso cuando el comando permanece igual. También puedes cambiar el nombre de un Job existente:
>>> hf jobs run --name training-v2 python:3.12 python train.py
>>> hf jobs labels <job_id> --name training-v2Use --status, --label y --name en hf jobs ls para filtrar Jobs. --status acepta uno o más estados, --label acepta pares key=value y --name es un atajo para --label name=NAME. Un Job debe coincidir con todos los filtros para ser listado. El nombre del Job también se muestra como su propia columna NAME:
# Show completed Jobs
>>> hf jobs ls -a --status completed
# Show running or scheduling Jobs
>>> hf jobs ls --status running,scheduling
# Show Jobs named `training-v2`
>>> hf jobs ls -a --name training-v2
# Show Jobs with the `model=Qwen3-06B` label
>>> hf jobs ls -a --label model=Qwen3-06B
# Combine filters: running Jobs labelled both `env=prod` and `team=ml`
>>> hf jobs ls --status running --label env=prod --label team=mlPor defecto, hf jobs ps muestra un máximo de 100 Jobs para evitar saturar la terminal. Use --limit para cambiar esto, o --limit 0 para mostrarlos todos:
# Show up to 500 Jobs
>>> hf jobs ps -a --limit 500
# Show all Jobs (no limit)
>>> hf jobs ps -a --limit 0Exponer los puertos del trabajo
Use --expose para un puerto protegido por token y --expose-public para un puerto que debe permitir el acceso sin autenticación. Ambas banderas se pueden repetir y combinar, y funcionan con Docker, UV y Jobs programados.
# Start a Job with a public HTTP server
>>> hf jobs run --detach --expose-public 8000 python:3.12 python -m http.server 8000
# Replace the configuration on a running Job: port 8000 is private, 9000 is public
>>> hf jobs expose <job_id> 8000 --public 9000
# Close all exposed ports
>>> hf jobs expose <job_id> --clearhf jobs expose toma los puertos protegidos por token como argumentos posicionales y los puertos públicos con --public. Aplica el cambio sin volver a ejecutar el Job. Los puertos omitidos en la lista de reemplazo se cierran.
Conectarse a un trabajo mediante SSH
Pasa --ssh a hf jobs run (o hf jobs uv run) para que el contenedor del Job sea accesible por SSH y luego conéctate con hf jobs ssh:
# Start a job with SSH enabled
>>> hf jobs run --ssh --detach python:3.12 sleep infinity
# Open an SSH session into it
>>> hf jobs ssh <job_id>
# Print the SSH command instead of running it
>>> hf jobs ssh <job_id> --dry-run
# Use a specific identity file
>>> hf jobs ssh <job_id> -i ~/.ssh/id_ed25519Solo se permite el acceso a los usuarios con permisos de escritura en el espacio de nombres del Job (el creador del Job o los miembros de la organización propietaria), autenticados mediante una clave pública SSH registrada en https://huggingface.co/settings/keys.
Grupos de red
Pase --network-group <name> a hf jobs run (o hf jobs uv run) para que los Jobs del mismo espacio de nombres y grupo de recursos puedan comunicarse entre sí en todos los puertos. Dentro de cada miembro, $HF_NETWORK_GROUP_HOSTNAME se resuelve a todos los Jobs del grupo, y ${HF_NETWORK_GROUP_PREFIX}<alias> a los miembros que reclamaron un alias con --network-alias <alias>:
# Start a server, reachable by the other members of the group as "master"
>>> hf jobs run --detach --network-group train --network-alias master python:3.12 python -m http.server 8000
# Start a client in the same group
>>> hf jobs run --detach --network-group train python:3.12 sh -c 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'Los miembros son resolubles antes de estar listos, por lo que debe conectarse con reintentos. Los nombres y alias de grupo son alfanuméricos en minúsculas y guiones, con un máximo de 46 y 34 caracteres, respectivamente.
UV Scripts (Experimental)
Ejecuta scripts de UV (scripts de Python con dependencias integradas) en la infraestructura de HF. Los scripts de UV son scripts de Python que incluyen sus dependencias directamente en el archivo mediante una sintaxis de comentario especial.
# Run a UV script (creates temporary repo)
>>> hf jobs uv run my_script.py
# Run with persistent repo
>>> hf jobs uv run --repo my-uv-scripts my_script.py
# Run with GPU
>>> hf jobs uv run --flavor t4-small ml_training.py
# Pass arguments to script
>>> hf jobs uv run process.py input.csv output.parquet
# Add dependencies
>>> hf jobs uv run --with transformers --with torch train.py
# Run a script directly from a URL
>>> hf jobs uv run https://huggingface.co/datasets/username/scripts/resolve/main/example.py
# Run a command
>>> hf jobs uv run --with lighteval python -c 'import lighteval'Los scripts de UV son scripts de Python que incluyen sus dependencias directamente en el archivo mediante una sintaxis de comentario especial. Esto los hace perfectos para tareas autónomas que no requieren configuraciones de proyecto complejas. Obtenga más información sobre los scripts de UV en la documentación de UV.
Use -- para pasar opciones en conflicto a su script. Aquí, --help llega a train.py en lugar de mostrar la ayuda de Jobs:
>>> hf jobs uv run --flavor t4-small train.py -- --helpEsto también se aplica a las banderas de formato: hf jobs run, hf jobs uv run y sus variantes scheduled consumen --format, --json y -q dondequiera que aparezcan, por lo que use -- cuando su script las necesite.
Incluya la configuración de lanzamiento con el script
Algunos scripts solo se ejecutan correctamente en un entorno de ejecución específico: una imagen determinada, un tipo de GPU, un intérprete de sistema, etc. Un script puede llevar esa configuración consigo mismo en una tabla opcional [tool.hf-jobs] en su encabezado PEP 723:
# /// script
# requires-python = ">=3.11"
# dependencies = ["vllm", "datasets"]
#
# [tool.hf-jobs]
# name = "unlimited-ocr"
# image = "vllm/vllm-openai:unlimited-ocr"
# flavor = "l4x1"
# python = "/usr/bin/python3"
# timeout = "2h"
# env = { PYTHONPATH = "/usr/local/lib/python3.12/dist-packages", BATCH_SIZE = "64" }
# secrets = ["HF_TOKEN"]
# labels = { task = "ocr" }
# volumes = ["hf://datasets/org/pdfs:/input"]
# ///hf jobs uv run ocr.py in_ds out_ds se lanza con el runtime adecuado, en lugar de ejecutarse en silencio en una imagen de CPU con el intérprete incorrecto. La tabla es invisible para un uv run normal: las tablas [tool.*] forman parte de PEP 723 y las herramientas ignoran las que no les pertenecen.
Claves admitidas, todas opcionales: image, flavor, python, timeout, name, namespace, env, secrets, labels, volumes, network_group y network_aliases. Se corresponden con las banderas del mismo nombre (name se almacena como la etiqueta name, volumes acepta las mismas especificaciones hf://...:/MOUNT_PATH que -v, network_aliases es una lista de valores de --network-alias). Una clave desconocida es un error en lugar de una intención descartada silenciosamente: un error tipográfico como flavour es exactamente el fallo que esta función existe para prevenir.
Todos los valores deben ser cadenas de texto, incluidos los valores de env y labels: -e BATCH_SIZE=64 se traduce a env = { BATCH_SIZE = "64" }, no a env = { BATCH_SIZE = 64 } (TOML interpreta este último como un entero y la tabla se rechaza). La única excepción es timeout, que también acepta un número entero de segundos (timeout = 7200 es lo mismo que timeout = "2h").
Los valores del script son valores predeterminados: una bandera explícita siempre tiene prioridad, y env, secrets, labels y volumes se fusionan entrada por entrada, por lo que -e y -v pueden añadirse a lo que declara el script:
# Same script, on bigger hardware, with one extra env var
>>> hf jobs uv run --flavor a10g-large -e BATCH_SIZE=64 ocr.py in_ds out_dsnetwork_aliases es la excepción: los alias que un Job declara forman un conjunto, por lo que --network-alias reemplaza la lista del script en lugar de añadirse a ella. Los Jobs programados no tienen ningún grupo de red, por lo que hf jobs scheduled uv run rechaza un script que declare network_group o network_aliases.
secrets solo lista los nombres de los secretos: los valores siempre provienen del entorno de quien ejecuta el script, nunca del propio script (HF_TOKEN también se resuelve desde hf auth login). Un secreto solicitado pero no definido localmente es un error, en lugar de que un Job reciba silenciosamente un valor vacío. Con --dry-run se muestra como <not set> en su lugar, de modo que la configuración de un script cuyos secretos aún no están provisionados siga siendo visible.
Cada ejecución muestra la configuración que envía, marcando los valores que provienen del script. Usa --dry-run para imprimirla sin lanzar nada:
>>> hf jobs uv run --dry-run --flavor a10g-large ocr.py in_ds out_ds
Warning: The script's [tool.hf-jobs] table requests HF_TOKEN: the value(s) from your local environment would be sent to the Job.
Job configuration:
script ocr.py
args in_ds out_ds
image vllm/vllm-openai:unlimited-ocr (from script)
flavor a10g-large
python /usr/bin/python3 (from script)
timeout 2h (from script)
env PYTHONPATH=/usr/local/lib/python3.12/dist-packages (from script)
BATCH_SIZE=64 (from script)
secrets HF_TOKEN=*** (from script)
volumes hf://datasets/org/pdfs:/input (from script)
labels task=ocr (from script)
name=unlimited-ocr (from script)
(dry run) Job not submitted.Esto también funciona para scripts que se encuentran detrás de una URL: el script se descarga una vez cuando se envía el Job (para leer su encabezado) y se envía al Job como un script local, en lugar de ser descargado nuevamente por el contenedor. La URL debe ser accesible desde tu máquina. Al igual que los scripts locales, los scripts de URL usan el montaje de artefactos reservado
/data; usa otra ruta de montaje para tus volúmenes de entrada.
Para hf jobs scheduled uv run, esto fija el script a su contenido en el momento de la creación. Actualizar la URL de origen ya no modifica las ejecuciones futuras: recrea el Job programado para incorporar una nueva versión.
--dry-run también está disponible en hf jobs run, hf jobs scheduled run y hf jobs scheduled uv run. Omite el envío y las cargas de volúmenes locales. Los nombres generados automáticamente para ambos tipos de Jobs, Docker y UV, incluyen la configuración de inicio resuelta, por lo que cambiar la configuración de tiempo de ejecución o los valores del entorno modifica el nombre.
hf jobs scheduled
Programa y gestiona trabajos que se ejecutarán en la infraestructura de HF.
El programa debe ser uno de @annually, @yearly, @monthly, @weekly, @daily, @hourly o una expresión de programación CRON (p. ej., "0 9 * * 1" para las 9:00 a. m. de cada lunes).
# Schedule a job that runs every hour
>>> hf jobs scheduled run @hourly --name hourly-task python:3.12 python -c 'print("This runs every hour!")'
# Use the CRON syntax
>>> hf jobs scheduled run "*/5 * * * *" python:3.12 python -c 'print("This runs every 5 minutes!")'
# Schedule with GPU
>>> hf jobs scheduled run @hourly --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'
# Schedule a UV script
>>> hf jobs scheduled uv run @hourly --name hourly-script my_script.pyUse los mismos parámetros que hf jobs run para pasar variables de entorno, secretos, timeout, etc.
Gestionar trabajos programados usando
# List your active scheduled jobs
>>> hf jobs scheduled ls
# Same filters as `hf jobs ls`: --status, --label and --name
>>> hf jobs scheduled ls --all
>>> hf jobs scheduled ls --status suspended
>>> hf jobs scheduled ls --name hourly-task --label env=prod
# Inspect the status of a job
>>> hf jobs scheduled inspect <scheduled_job_id>
# Suspend (pause) a scheduled job
>>> hf jobs scheduled suspend <scheduled_job_id>
# Resume a scheduled job
>>> hf jobs scheduled resume <scheduled_job_id>
# Change future run times (Mondays at 9:00)
>>> hf jobs scheduled reschedule <scheduled_job_id> "0 9 * * 1"
# Trigger a scheduled job to run right now (does not change the schedule)
>>> hf jobs scheduled trigger <scheduled_job_id>
# Delete a scheduled job
>>> hf jobs scheduled delete <scheduled_job_id>hf sandbox
hf sandbox inicia máquinas en la nube aisladas basadas en Jobs: crea una, ejecuta comandos con salida en tiempo real y copia archivos dentro y fuera. Cualquier imagen de Docker con /bin/sh funciona. Consulta la guía de Sandboxes para la API de Python y la guía conceptual para ver cómo funciona por debajo.
Los sandbox son experimentales y su API y comportamiento pueden cambiar sin previo aviso. Los sandbox compartidos están destinados a cargas de trabajo dentro del mismo límite de confianza; use un sandbox dedicado para cargas de trabajo que no se confían entre sí.
# Create a sandbox (waits until it is ready, prints its id)
>>> hf sandbox create
✓ Sandbox ready id=687f911eaea852de79c4a50a image=python:3.12 elapsed=6.0s
# Attach labels to the underlying Job
>>> hf sandbox create --label controller-run=run-42 --label team=data-infra
# Run commands inside it (output is streamed, exit code is propagated)
>>> hf sandbox exec 687f911eaea852de79c4a50a -- python -c "print('hi')"
hi
# Copy files in and out (docker-style)
>>> hf sandbox cp data.csv 687f911eaea852de79c4a50a:/data/data.csv
>>> hf sandbox cp 687f911eaea852de79c4a50a:/app/results.json results.json
# Terminate a sandbox
>>> hf sandbox kill 687f911eaea852de79c4a50aUse --flavor para elegir el hardware (p. ej. a10g-small), --idle-timeout para limitar la vida útil del sandbox y -l / --label para adjuntar etiquetas a su Job. Para desplegar muchos sandboxes de CPU económicos, prepare un pool con hf sandbox pool create y cree instancias en él con hf sandbox create --pool <id> (consulte la guía de Sandboxes).
Pasar variables de entorno y secretos a un sandbox
Hay dos canales separados, con propiedades de almacenamiento diferentes:
| canal | flags | sandbox dedicado | sandbox agrupado (--pool) |
|---|---|---|---|
| entorno | -e / --env, --env-file | almacenado en los metadatos del trabajo | entregado al host en la creación, no almacenado en los metadatos del trabajo |
| secrets | -s / --secrets, --secrets-file | en el servidor | no disponible — usa --env |
# Plain environment variables
>>> hf sandbox create -e LOG_LEVEL=debug --env-file .env
# Secrets, read from your environment by name (nothing sensitive on the command line)
>>> hf sandbox create -s OPENAI_API_KEY -s HF_TOKEN
# Secrets from a file, or piped in on stdin
>>> hf sandbox create --secrets-file .env.secrets
>>> printf 'OPENAI_API_KEY=sk-...\n' | hf sandbox create --secrets-file --s KEY=value también funciona, pero el valor queda en el historial de la shell y en la lista de procesos, por lo que la CLI emite una advertencia en stderr, incluso en modo silencioso. Los sandbox agrupados rechazan --secrets de plano: un pool no tiene un canal de secretos cifrados, y hf sandbox create --pool <id> -s KEY=value devuelve un error con una referencia a --env.
hf webhooks
hf webhooks te permite gestionar webhooks en Hugging Face Hub directamente desde la terminal. Los webhooks te permiten escuchar eventos (pushes, discusiones, etc.) en repositorios, usuarios u organizaciones y activar acciones, ya sea enviando un ping a una URL remota o ejecutando un Job en la infraestructura de Hugging Face.
Listar webhooks
>>> hf webhooks ls
ID URL DISABLED DOMAINS WATCHED
wh-abc123 https://example.com/hook False repo model:bert-base-uncased
wh-def456 https://example.com/other-hook False repo org:HuggingFaceUse --format json para una salida legible por máquina, o -q para imprimir solo los IDs:
>>> hf webhooks ls --format json
>>> hf webhooks ls -qObtener información del webhook
>>> hf webhooks info wh-abc123Imprime los detalles completos del webhook como JSON.
Crear un webhook
Crea un webhook que envía cargas útiles a una URL:
>>> hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased
>>> hf webhooks create --url https://example.com/hook --watch org:HuggingFace --watch model:gpt2 --domain repoO crea un webhook que active un Job en su lugar:
>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-cLos secretos del Job de origen no se copian al webhook. Use --secrets o --secrets-file (misma sintaxis que hf jobs run) para pasarlos al Job activado. Por ejemplo, --secrets HF_TOKEN pasa su token local de Hugging Face:
>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch bucket:my-org/my-bucket --secrets HF_TOKENLa opción --watch utiliza el formato type:name, donde type es uno de model, dataset, space, bucket, org o user. Puede repetirse para observar varios elementos. Utilice --domain para filtrar eventos a repo o discussion, y --secret para establecer un secreto de firma.
Actualizar un webhook
>>> hf webhooks update wh-abc123 --url https://new-url.com/hook
>>> hf webhooks update wh-abc123 --watch model:gpt2 --domain repoSolo se modifican las opciones proporcionadas. Tenga en cuenta que --watch reemplaza la lista completa observada cuando se especifica.
Para actualizar los secretos de un webhook activado por un Job, pase --job-id junto con --secrets. Los secretos enumerados reemplazan los valores almacenados y todos los demás secretos se conservan:
>>> hf webhooks update wh-abc123 --job-id 687f911eaea852de79c4a50a --secrets HF_TOKENActivar / desactivar un webhook
>>> hf webhooks enable wh-abc123
>>> hf webhooks disable wh-abc123Eliminar un webhook
>>> hf webhooks delete wh-abc123
Are you sure you want to delete webhook 'wh-abc123'? [y/N]: y
Webhook deleted: wh-abc123Use --yes para omitir el mensaje de confirmación:
>>> hf webhooks delete wh-abc123 --yesTodos los comandos aceptan
--tokenpara sobrescribir la autenticación. Use--helpen cualquier comando para ver todas las opciones.
hf endpoints
Use hf endpoints para listar, desplegar, describir y gestionar Inference Endpoints directamente desde la terminal. El alias heredado hf inference-endpoints sigue disponible por compatibilidad.
# Lists endpoints in your namespace
>>> hf endpoints ls
# List the hardware you can deploy on
>>> hf endpoints hardware
# Deploy an endpoint from Model Catalog
>>> hf endpoints catalog deploy --repo openai/gpt-oss-120b --name my-endpoint
# Deploy an endpoint from the Hugging Face Hub
>>> hf endpoints deploy my-endpoint --repo gpt2 --framework pytorch --accelerator cpu --instance-size x2 --instance-type intel-icl
# List catalog entries
>>> hf endpoints catalog ls
# Show status and metadata
>>> hf endpoints describe my-endpoint
# Pause the endpoint
>>> hf endpoints pause my-endpoint
# Delete without confirmation prompt
>>> hf endpoints delete my-endpoint --yesAgregue
--namespacepara apuntar a una organización y--tokenpara sobrescribir la autenticación.
Encuentra hardware para desplegar
hf endpoints deploy requiere cinco banderas de hardware (--vendor, --region, --accelerator, --instance-type y --instance-size). hf endpoints hardware lista las combinaciones válidas, con el precio por réplica por hora en USD y la cuota de aceleradores de tu espacio de nombres:
>>> hf endpoints hardware --vendor aws --region eu-west-1
VENDOR REGION ACCELERATOR INSTANCE_TYPE INSTANCE_SIZE MEMORY_GB GPU_MEMORY_GB PRICE_PER_HOUR QUOTA STATUS
------ --------- ----------- ------------- ------------- --------- ------------- -------------- ----- ---------
aws eu-west-1 cpu intel-spr x1 2.0 0.033 0/60 available
aws eu-west-1 cpu intel-spr x2 4.0 0.067 0/60 available
aws eu-west-1 cpu intel-spr x4 8.0 0.134 0/60 available
aws eu-west-1 cpu intel-spr x8 16.0 0.268 0/60 available
aws eu-west-1 cpu intel-spr x16 32.0 0.536 0/60 available
aws eu-west-1 gpu nvidia-a10g x1 30.0 24 1.0 0/16 available
aws eu-west-1 gpu nvidia-t4 x1 15.0 16 0.5 1/30 available
Hint: Deploy on one of these, e.g.: hf endpoints deploy my-endpoint --repo <repo> --framework <framework> --vendor aws --region eu-west-1 --accelerator cpu --instance-type intel-spr --instance-size x1Las banderas de filtro son las banderas de despliegue (--vendor, --region, --accelerator, --instance-type), por lo que lo que filtres es lo que pasas a deploy. Solo se lista el hardware en el que puedes desplegar ahora mismo: un estado utilizable y suficiente cuota de aceleradores restante en tu espacio de nombres para una réplica. Añade --all para ver también lo que está deprecado, temporalmente no disponible o sin cuota. --format json añade las especificaciones restantes por réplica (vCPUs, arquitectura, número de aceleradores) a cada entrada.
La cuota es por espacio de nombres y determina qué filas se listan en absoluto. Si estás desplegando en una organización, pasa el mismo
--namespaceque pasarás adeploy; de lo contrario, estarás viendo tu cuota personal, que puede tanto ocultar hardware en el que la organización puede desplegar como mostrar hardware en el que no puede.
Desplegar un contenedor personalizado
Para desplegar tu propia imagen de Docker en lugar de una gestionada por Hugging Face, pasa --framework custom junto con --custom-image. El repositorio del modelo se monta en /repository dentro del contenedor. Usa --container-args (y opcionalmente --container-command) para pasar una cadena de lanzamiento entre comillas, --env/--secrets para inyectar variables de entorno y --type para establecer el tipo de acceso (public, authenticated o private):
>>> hf endpoints deploy nex-n2-pro \
--repo nex-agi/Nex-N2-Pro \
--framework custom \
--accelerator gpu --vendor aws --region us-east-1 \
--instance-type nvidia-h200 --instance-size x8 \
--custom-image nexagi/sglang:v0.5.12 \
--health-route /health --port 30000 \
--container-args "--reasoning-parser qwen3 --tool-call-parser qwen3_coder --mamba-scheduler-strategy extra_buffer --tp 8" \
--env MODEL_ID=/repository \
--type authenticated--container-args y --container-command no están limitados a imágenes personalizadas: se mapean a model.args y model.command en el payload de la API, que también se aplican a las imágenes gestionadas. En un endpoint existente, ambas banderas reemplazan el valor actual en lugar de añadirse a él, por lo que debe pasar la lista completa que desee y usar una cadena vacía para borrarla. Los endpoints desplegados desde el catálogo ya vienen con banderas de motor ajustadas, así que compruebe hf endpoints describe antes de sobrescribirlos:
>>> hf endpoints update my-endpoint \
--container-args "--enable-auto-tool-choice --tool-call-parser lfm2"Desplegar una imagen de motor administrada
--custom-image por sí solo despliega un contenedor arbitrario. Añada --engine para ejecutarlo como uno de los motores que gestiona la API (vllm, sglang, tgi, tei, llamacpp, hf-serve, …), lo que habilita la configuración de ese motor, incluido --tensor-parallel-size y --data-parallel-size. vLLM y SGLang usan un acelerador por defecto, mientras que el punto de acceso recibe todos los aceleradores de su instancia; por lo tanto, dejar ambos sin configurar cargaría el modelo en uno y dejaría el resto inactivo, aunque el sistema seguiría reportando un estado saludable. Por eso la API ahora rechaza esa configuración:
>>> hf endpoints deploy gpt-oss-120b-vllm \
--repo openai/gpt-oss-120b \
--framework custom \
--accelerator gpu --vendor aws --region us-east-1 \
--instance-type nvidia-h200 --instance-size x8 \
--engine vllm --custom-image vllm/vllm-openai:v0.23.0 \
--tensor-parallel-size 8Esto no es lo mismo que --container-args "... --tp 8" de arriba: --tensor-parallel-size escribe en la configuración model.image del motor, que es lo que la API valida contra el número de aceleradores de la instancia, mientras que --container-args solo añade una bandera a la línea de comandos. Use --container-args para banderas del motor que no tienen un campo de imagen, y para contenedores personalizados simples, que no tienen campos de paralelismo.
Para retunear un endpoint en ejecución, pase los tamaños por separado. model.image se envía como un todo y requiere url, por lo que la imagen actual del endpoint se recupera y se actualiza en su lugar:
>>> hf endpoints update gpt-oss-120b-vllm --tensor-parallel-size 4 --data-parallel-size 2hf endpoints update también acepta --custom-image y --engine, la única forma de cambiar la imagen de un endpoint desde la CLI. Esa ruta reemplaza model.image en lugar de parchearla, por lo que ejecuta hf endpoints describe primero y pasa de vuelta lo que quieras conservar.
hf endpoints catalog
Use hf endpoints catalog para interactuar con el Catálogo de modelos de Inference Endpoints. Despliegue modelos directamente desde el catálogo con configuraciones optimizadas.
Cada modelo del catálogo incluye una o más recetas: una combinación de hardware y motor que ha sido probada para él. hf endpoints catalog ls imprime una fila por receta, por lo que un modelo con recetas tanto para GPU como para Neuron aparece dos veces:
# List available catalog models
>>> hf endpoints catalog ls
REPO_ID TASK LICENSE ACCELERATOR ENGINE GGUF_FILE RECIPE_ID
----------------------------------- ------------------ ---------- ----------- -------- ----------------------------- -------------------------
meta-llama/Llama-3.1-8B-Instruct text-generation Llama 3.1 gpu vllm sizzling-biryani-g4xsi1ac
meta-llama/Llama-3.1-8B-Instruct text-generation Llama 3.1 neuron vllmNeuron artisanal-quinoa-yz9ynamx
bartowski/QwQ-32B-Preview-GGUF text-generation Apache 2.0 gpu llamacpp QwQ-32B-Preview-Q8_0.gguf baked-orange-m863gx7d
# Narrow it down
>>> hf endpoints catalog ls --engine vllm --task text-generation --search llama --limit 10--accelerator, --engine, --license, --task, --search y --limit filtran en el servidor.
# Deploy the default recipe of a model
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct
# Deploy an exact recipe listed above
>>> hf endpoints catalog deploy --recipe artisanal-quinoa-yz9ynamx
# Deploy with a custom name
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct --name my-llama-endpointCon --repo, la receta predeterminada puede acotarse con --accelerator (cpu, gpu, neuron) y --gguf-file (para modelos que tienen una receta por cuantización). Ambos se rechazan junto con --recipe, que ya designa una única receta.