Hub Python Library documentation
Interface en ligne de commande (CLI)
Interface en ligne de commande (CLI)
Le package Python huggingface_hub inclut une CLI intégrée nommée hf. Cet outil vous permet d’interagir avec le Hugging Face Hub directement depuis un terminal. Par exemple, vous pouvez vous connecter à votre compte, créer un dépôt, téléverser et télécharger des fichiers, etc. Il propose également des fonctionnalités pratiques pour configurer votre machine ou gérer votre cache. Dans ce guide, nous examinerons les principales fonctionnalités de la CLI et comment les utiliser.
Ce guide présente les fonctionnalités les plus importantes de l'interface en ligne de commande
hf. Pour une référence complète de toutes les commandes et options, consultez la référence de l'interface en ligne de commande.
Utiliser la CLI
hfavec des agents IA ? Installez le Skill et consultez le guide 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 addL'installateur autonome l'installe pour vous (voir ci-dessous), et
hf updatele met à jour.
Premiers pas
Installateur autonome (Recommandé)
Vous pouvez installer le CLI hf avec une seule commande :
Sur macOS et Linux :
>>> curl -LsSf https://hf.co/cli/install.sh | bashSous Windows :
>>> powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"L’installateur installe également la compétence hf-cli de manière globale, pour Claude Code et tout agent lisant ~/.agents/skills. Passez --exclude-skill pour l’ignorer :
>>> 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"Une fois installé, vous pouvez vérifier que le CLI est correctement configuré :
>>> 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 le CLI est correctement installé, vous devriez voir la liste de toutes les options disponibles dans le CLI. Si vous obtenez un message d'erreur tel que command not found: hf, veuillez consulter le guide Installation.
L'option
--helpest très pratique pour obtenir plus de détails sur une commande. Vous pouvez l'utiliser à tout moment pour lister toutes les options disponibles et leurs détails. Par exemple,hf upload --helpfournit plus d'informations sur la manière de téléverser des fichiers à l'aide de l'interface en ligne de commande.
Utiliser uv
La façon la plus simple d'utiliser le CLI hf est avec uvx. Il exécute toujours la dernière version dans un environnement isolé - aucune installation n'est nécessaire !
Assurez-vous que uv est installé au préalable. Consultez le guide d'installation de uv pour les instructions.
Utilisez ensuite l’interface en ligne de commande directement :
>>> uvx hf auth login
>>> uvx hf download
>>> uvx hf ...
uvx hfutilise le paquet PyPIhf.
Installer avec pip
Le CLI est également fourni avec le package principal huggingface_hub :
>>> pip install -U "huggingface_hub"Utiliser Homebrew
Vous pouvez également installer le CLI à l'aide de Homebrew :
>>> brew install hfConsultez la page Homebrew huggingface ici pour plus de détails.
Mise à jour
Pour passer à la dernière version, exécutez :
>>> hf updateCette commande détecte la méthode d’installation de hf (Homebrew, installateur autonome ou pip) et exécute la commande de mise à jour correspondante. Si la compétence hf-cli est installée globalement, elle est également actualisée afin que les agents prennent en compte la nouvelle interface de commandes. Sinon, elle reste désinstallée : une mise à jour ne la réinstalle jamais si vous l’aviez ignorée ou supprimée.
Par défaut, l'interface en ligne de commande affiche également un avertissement jaune d'une ligne sur stderr lorsqu'une version plus récente est disponible sur PyPI. Pour le désactiver (par exemple dans un CI hors ligne), définissez HF_HUB_DISABLE_UPDATE_CHECK=1.
Formatage de la sortie
La plupart des commandes hf acceptent le même ensemble de drapeaux de formatage globaux. Ils sont documentés dans une section Formatting options dédiée de chaque page --help et peuvent être ajoutés à n'importe quelle commande sans avoir à les déclarer pour chaque commande :
| Drapeau | Équivalent | Description |
|---|---|---|
--format <value> | — | Choisissez explicitement le format de sortie. Valeurs acceptées : auto (par défaut), human, agent, json, quiet. |
--json | --format json | Affiche un JSON structuré. Utile pour l'envoyer en entrée de jq ou d'autres scripts. |
-q, --quiet | --format quiet | Affiche uniquement les identifiants (un par ligne). Utile pour transmettre les identifiants à d'autres commandes. |
--no-truncate | — | Afficher les valeurs complètes dans les tableaux humains au lieu d’abréger les valeurs longues avec .... Le tableau peut dépasser la largeur du terminal. Utilisez --format json pour une sortie structurée des colonnes de type liste/dictionnaire. |
auto (par défaut) sélectionne human pour un terminal interactif et agent lorsque le CLI est appelé par un agent IA. human ajoute des couleurs et des tableaux soignés ; agent produit des valeurs séparées par des tabulations sans troncature ; json émet un objet ou un tableau JSON compact. Mélanger deux drapeaux de mode de sortie (par ex. --json avec --format table) provoque une erreur d’utilisation.
Les tableaux humains s’adaptent automatiquement à la largeur de votre terminal : les colonnes les plus larges sont raccourcies uniquement lorsque les largeurs naturelles débordent de l’écran (ainsi, sur un terminal large, vous voyez généralement les valeurs complètes sans ...). Passez --no-truncate pour forcer l’affichage des valeurs complètes quelle que soit la largeur ; utilisez --format json pour une sortie structurée des colonnes de type liste/dictionnaire.
# 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
Dans de nombreux cas, vous devez être connecté à un compte Hugging Face pour interagir avec le Hub (télécharger des dépôts privés, téléverser des fichiers, créer des PR, etc.). Pour ce faire, exécutez la commande suivante dans votre terminal :
>>> hf auth loginSi vous êtes déjà connecté, cette commande ignore l’invite et affiche un message. Pour forcer la reconnexion (par exemple pour changer de jeton), utilisez --force :
>>> hf auth login --forcePar défaut, la commande vous connecte via votre navigateur : elle affiche une URL et un code court. Ouvrez l’URL, saisissez le code, approuvez la demande, et le CLI récupère et enregistre un jeton d’accès sur votre machine. Le jeton expire après un certain temps, mais il est renouvelé automatiquement tant que vous continuez à l’utiliser.
? 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.Vous pouvez également choisir de coller un User Access Token généré depuis votre Settings page, soit de manière interactive (en sélectionnant Paste an access token), soit directement depuis la ligne de commande. Pour plus de sécurité, nous recommandons de passer votre jeton en tant que variable d’environnement afin d’éviter de le coller dans l’historique de vos commandes.
# 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`Lorsqu’il est exécuté par un agent IA (détection automatique, ou avec --format agent), la commande ne demande jamais de confirmation : elle exécute le flux du navigateur et affiche des instructions simples que l’agent peut transmettre à son utilisateur, puis attend l’autorisation :
>>> 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 est interactif, donc --format json et --format quiet ne sont pas pris en charge : utilisez --token pour les connexions scriptées, non interactives.
Pour plus de détails sur l'authentification, consultez cette section.
hf auth whoami
Si vous souhaitez savoir si vous êtes connecté, vous pouvez utiliser hf auth whoami. Cette commande ne possède aucune option et affiche simplement votre nom d’utilisateur ainsi que les organisations auxquelles vous appartenez sur le Hub :
hf auth whoami
Wauplin
orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolClusterSi vous n'êtes pas connecté, un message d'erreur sera affiché.
hf auth logout
Cette commande vous déconnecte. En pratique, elle supprime tous les jetons stockés sur votre machine. Si vous souhaitez supprimer un jeton spécifique, vous pouvez spécifier le nom du jeton en tant qu'argument.
Cette commande ne vous déconnectera pas si vous êtes connecté à l’aide de la variable d’environnement HF_TOKEN (voir référence). Dans ce cas, vous devez désactiver la variable d’environnement dans la configuration de votre machine.
hf download
Utilisez la commande hf download pour télécharger des fichiers directement depuis le Hub. En interne, elle utilise les mêmes fonctions d'aide hf_hub_download() et snapshot_download() décrites dans le guide Téléchargement et affiche le chemin retourné dans le terminal. Dans les exemples ci-dessous, nous passons en revue les cas d'utilisation les plus courants. Pour obtenir la liste complète des options disponibles, vous pouvez exécuter :
hf download --helpTélécharger un fichier unique
Pour télécharger un fichier unique d'un dépôt, fournissez simplement le repo_id et le nom du fichier comme suit :
>>> 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.jsonLa commande affiche toujours sur la dernière ligne le chemin du fichier sur votre machine locale.
Pour télécharger un fichier situé dans un sous-répertoire du dépôt, vous devez fournir le chemin du fichier dans le dépôt au format posix, comme ceci :
>>> hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensorsTélécharger un dépôt entier
Dans certains cas, vous souhaitez simplement télécharger tous les fichiers d'un dépôt. Cela peut se faire en spécifiant uniquement l'identifiant du dépôt :
>>> 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/3bac358730f8806e5c3dc7c7e19eb36e045bf720Télécharger plusieurs fichiers
Vous pouvez également télécharger un sous-ensemble de fichiers d'un dépôt avec une seule commande. Cela peut se faire de deux manières. Si vous disposez déjà d'une liste précise des fichiers que vous souhaitez télécharger, il vous suffit de les fournir séquentiellement :
>>> 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/11c5a3d5811f50298f278a704980280950aedb10L'autre approche consiste à fournir des motifs pour filtrer les fichiers que vous souhaitez télécharger à l'aide de --include et --exclude. Par exemple, si vous voulez télécharger tous les fichiers safetensors de stabilityai/stable-diffusion-xl-base-1.0, à l'exception des fichiers en précision 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/462165984030d82259a11f4367a4eed129e94a7bTélécharger un jeu de données, un Space ou un kernel
Les exemples ci-dessus montrent comment télécharger depuis un dépôt de modèle. Pour télécharger un jeu de données, un Space ou un kernel, utilisez l’option --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
...Télécharger une révision spécifique
Les exemples ci-dessus montrent comment télécharger depuis le dernier commit de la branche principale. Pour télécharger depuis une révision spécifique (hash de commit, nom de branche ou tag), utilisez l'option --revision :
>>> hf download bigcode/the-stack --repo-type dataset --revision v1.1
...Utiliser un URI hf://
Au lieu de passer le type de dépôt, la révision et le chemin du fichier comme arguments et options distincts, vous pouvez fournir un unique URI hf://. L’URI encode tout d’un coup, en suivant la grammaire hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (voir la référence des URI HF pour la syntaxe complète) :
# 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.jsonLorsqu’un URI est fourni, --repo-type et --revision ne peuvent pas non plus être définis, car ils font déjà partie de l’URI (une erreur est levée dans le cas contraire), et un chemin de fichier intégré à l’URI ne peut pas être combiné avec des noms de fichiers positionnels. Un / final sur le chemin désigne un sous-dossier (comme pour l’argument positionnel). Les noms de branche contenant un / doivent être encodés en URL sous la forme %2F (par exemple hf://my-org/my-model@feature%2Ffoo).
Télécharger dans un dossier local
La méthode recommandée (et par défaut) pour télécharger des fichiers depuis le Hub est d’utiliser le système de cache. Toutefois, dans certains cas, vous souhaitez télécharger des fichiers et les déplacer vers un dossier spécifique. Cela est utile pour obtenir un flux de travail plus proche de ce que proposent les commandes git. Vous pouvez le faire en utilisant l’option --local-dir.
Un dossier .cache/huggingface/ est créé à la racine de votre répertoire local, contenant les métadonnées des fichiers téléchargés. Cela évite de retélécharger les fichiers s'ils sont déjà à jour. Si les métadonnées ont changé, la nouvelle version du fichier est téléchargée. Cela optimise le local-dir pour ne récupérer que les dernières modifications.
Pour plus de détails sur le fonctionnement du téléchargement vers un fichier local, consultez le guide download.
>>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu
...
fuyu/model-00001-of-00002.safetensorsMode de simulation
Dans certains cas, vous souhaitez vérifier quels fichiers seraient téléchargés avant de procéder au téléchargement. Vous pouvez le faire à l'aide du paramètre --dry-run. Il répertorie tous les fichiers à télécharger dans le dépôt et vérifie s'ils ont déjà été téléchargés. Cela donne une idée du nombre de fichiers à télécharger et de leur taille.
>>> 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 -Pour plus de détails, consultez le guide de téléchargement.
Spécifier le répertoire de cache
En l'absence de --local-dir, tous les fichiers sont téléchargés par défaut dans le répertoire de cache défini par la variable d'environnement HF_HOME. Vous pouvez spécifier un cache personnalisé à l'aide de --cache-dir :
>>> hf download adept/fuyu-8b --cache-dir ./path/to/cache
...
./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745Spécifier un jeton
Pour accéder aux dépôts privés ou protégés, vous devez utiliser un jeton. Par défaut, le jeton enregistré localement (à l'aide de hf auth login) est utilisé. Si vous souhaitez vous authentifier explicitement, utilisez l'option --token :
>>> hf download gpt2 config.json --token=hf_****
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.jsonMode silencieux
Par défaut, la commande hf download est verbale. Elle affiche des détails tels que des messages d'avertissement, des informations sur les fichiers téléchargés et des barres de progression. Si vous souhaitez tout cela en silence, utilisez l'option --quiet. Seule la dernière ligne (c'est-à-dire le chemin des fichiers téléchargés) est affichée. Cela peut s'avérer utile si vous souhaitez transmettre la sortie à une autre commande dans un script.
>>> hf download gpt2 --quiet
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10Délai d'attente de téléchargement
Sur les machines à connexion lente, vous pouvez rencontrer des problèmes de délai d’attente comme celui-ci :
`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)')`Pour atténuer ce problème, vous pouvez définir la variable d'environnement HF_HUB_DOWNLOAD_TIMEOUT sur une valeur plus élevée (la valeur par défaut est 10) :
export HF_HUB_DOWNLOAD_TIMEOUT=30Pour plus de détails, consultez la référence des variables d’environnement. Et relancez votre commande de téléchargement.
hf upload
Utilisez la commande hf upload pour téléverser des fichiers directement sur le Hub. En interne, elle utilise les mêmes fonctions d’aide upload_file() et upload_folder() décrites dans le guide Upload. Dans les exemples ci-dessous, nous passons en revue les cas d’utilisation les plus courants. Pour obtenir la liste complète des options disponibles, vous pouvez exécuter :
>>> hf upload --helpTéléverser un dossier entier
L'utilisation par défaut de cette commande est la suivante :
# Usage: hf upload [repo_id] [local_path] [path_in_repo]Pour téléverser le répertoire courant à la racine du dépôt, utilisez :
>>> hf upload my-cool-model . .
https://huggingface.co/Wauplin/my-cool-model/tree/main/Si le dépôt n'existe pas encore, il sera créé automatiquement.
Vous pouvez également téléverser un dossier spécifique :
>>> hf upload my-cool-model ./models .
https://huggingface.co/Wauplin/my-cool-model/tree/main/Enfin, vous pouvez téléverser un dossier vers une destination spécifique du dépôt :
>>> hf upload my-cool-model ./path/to/curated/data /data/train
https://huggingface.co/Wauplin/my-cool-model/tree/main/data/trainTéléverser un fichier unique
Vous pouvez également téléverser un fichier unique en définissant local_path pour qu’il pointe vers un fichier sur votre machine. Dans ce cas, path_in_repo est facultatif et prend par défaut le nom de votre fichier local :
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensorsSi vous souhaitez téléverser un fichier unique dans un répertoire spécifique, définissez path_in_repo en conséquence :
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensorsTéléverser plusieurs fichiers
Pour téléverser plusieurs fichiers d'un dossier d'un coup sans téléverser le dossier entier, utilisez les motifs --include et --exclude. Cela peut également être combiné avec l'option --delete pour supprimer les fichiers du dépôt pendant le téléversement de nouveaux fichiers. Dans l'exemple ci-dessous, nous synchronisons l'espace local en supprimant les fichiers distants et en téléversant tous les fichiers sauf ceux du dossier /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"
...Téléverser vers un jeu de données ou un Space
Pour téléverser vers un jeu de données ou un Space, utilisez l’option --repo-type :
>>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset
...Téléverser vers une organisation
Pour téléverser du contenu dans un dépôt appartenant à une organisation plutôt qu'à un dépôt personnel, vous devez le spécifier explicitement dans repo_id :
>>> hf upload MyCoolOrganization/my-cool-model . .
https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/Téléverser vers une révision spécifique
Par défaut, les fichiers sont téléversés sur la branche main. Si vous souhaitez téléverser des fichiers sur une autre branche ou référence, utilisez l’option --revision :
# Upload files to a PR
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...Remarque : si revision n'existe pas et que --create-pr n'est pas défini, une branche sera créée automatiquement à partir de la branche main.
Utiliser un URI hf://
Comme pour hf download, la destination peut être exprimée sous forme d'un unique URI hf:// suivant la grammaire hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (voir la référence des URI HF pour la syntaxe complète). Le type de dépôt, la révision et path_in_repo sont tous lus depuis l'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 ./modelsLorsqu’un URI est fourni, --repo-type et --revision ne peuvent pas non plus être définis, car ils font déjà partie de l’URI (une erreur est levée dans le cas contraire), et un chemin intégré à l’URI ne peut pas être combiné avec l’argument path_in_repo.
Téléverser et créer une PR
Si vous n’avez pas la permission de pousser vers un dépôt, vous devez ouvrir une PR et informer les auteurs des modifications que vous souhaitez apporter. Cela peut se faire en définissant l’option --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/Téléverser à intervalles réguliers
Dans certains cas, vous pouvez vouloir pousser des mises à jour régulières vers un dépôt. Par exemple, cela est utile si vous entraînez un modèle et que vous souhaitez téléverser le dossier de journaux toutes les 10 minutes. Vous pouvez le faire en utilisant l’option --every :
# Upload new logs every 10 minutes
hf upload training-model logs/ --every=10Spécifier un message de commit
Utilisez --commit-message et --commit-description pour définir un message et une description personnalisés pour votre commit au lieu des valeurs par défaut
>>> 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/mainSpécifier un jeton
Pour téléverser des fichiers, vous devez utiliser un jeton. Par défaut, le jeton enregistré localement (à l’aide de hf auth login) est utilisé. Si vous souhaitez vous authentifier explicitement, utilisez l’option --token :
>>> hf upload Wauplin/my-cool-model ./models . --token=hf_****
...
https://huggingface.co/Wauplin/my-cool-model/tree/mainMode silencieux
Par défaut, la commande hf upload est verbale. Elle affiche des détails tels que des messages d’avertissement, des informations sur les fichiers téléversés et des barres de progression. Si vous souhaitez tout cela en silence, utilisez l’option --quiet. Seule la dernière ligne (c’est-à-dire l’URL des fichiers téléversés) est affichée. Cela peut s’avérer utile si vous souhaitez transmettre la sortie à une autre commande dans un script.
>>> hf upload Wauplin/my-cool-model ./models . --quiet
https://huggingface.co/Wauplin/my-cool-model/tree/mainhf buckets
Utilisez hf buckets pour gérer les buckets sur le Hugging Face Hub. Les buckets offrent un stockage d’objets de type S3 sur Hugging Face, propulsé par le backend de stockage Xet. Contrairement aux dépôts (basés sur git et qui suivent l’historique des fichiers), les buckets sont des conteneurs de stockage d’objets distants conçus pour les fichiers de grande taille avec déduplication adressable par contenu. Ils sont destinés aux cas d’usage nécessitant un stockage simple, rapide et mutable, comme le stockage de points de contrôle d’entraînement, de journaux, d’artefacts intermédiaires ou de toute grande collection de fichiers qui n’a pas besoin de contrôle de version. Dans les exemples ci-dessous, nous passons en revue les cas d’usage les plus courants. Pour un guide complet, consultez le guide des Buckets.
Créer un bucket
Pour créer un nouveau bucket, utilisez hf buckets create. Le bucket sera créé par défaut sous votre espace de noms :
>>> hf buckets create my-bucketVous pouvez également créer un bucket privé à l'aide du drapeau --private :
>>> hf buckets create my-bucket --privateLister et inspecter les buckets
Pour lister tous vos buckets, utilisez hf buckets list (ou son raccourci hf buckets ls). Vous pouvez également lister les buckets d’une organisation spécifique :
>>> 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"Pour obtenir des informations détaillées sur un bucket spécifique (renvoyées au format JSON), utilisez 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
}Changer la visibilité du bucket
Pour passer un bucket de privé à public, ou inversement, utilisez hf buckets settings :
# Make a bucket private
>>> hf buckets settings username/my-bucket --private
# Make it public again
>>> hf buckets settings username/my-bucket --publicSupprimer un bucket
Pour supprimer un bucket, utilisez hf buckets delete. Une confirmation vous sera demandée, sauf si vous passez --yes :
>>> hf buckets delete username/my-bucket --yesSupprimer des fichiers
Utilisez hf buckets remove (ou son raccourci hf buckets rm) pour supprimer des fichiers d’un bucket.
Pour supprimer un fichier unique, spécifiez son chemin :
>>> hf buckets rm username/my-bucket/old-model.binPour supprimer tous les fichiers sous un préfixe, utilisez --recursive :
>>> hf buckets rm username/my-bucket/logs/ --recursiveVous pouvez également cibler tous les fichiers d’un bucket sans préfixe :
>>> hf buckets rm username/my-bucket --recursive --include "*.tmp"Utilisez --dry-run pour prévisualiser ce qui serait supprimé sans rien supprimer réellement :
>>> hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-runParcourir les fichiers
Utilisez hf buckets list avec un identifiant de bucket pour lister les fichiers d’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/Ajoutez -R pour un listing récursif et -h pour des tailles de fichiers lisibles et des dates courtes. Vous pouvez également afficher une vue arborescente ASCII avec --tree, ou utiliser --tree --quiet pour un arbre propre sans métadonnées :
# 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.txtPour filtrer par préfixe, ajoutez le préfixe au chemin du bucket :
>>> hf buckets list username/my-bucket/sub -RCopier les fichiers
Utilisez hf cp pour copier un fichier unique entre votre machine locale, des dépôts et des buckets. La source et la destination peuvent chacune être un chemin local, un URI hf:// (dépôt ou bucket) ou - (stdin/stdout).
hf cpest également exposé sous la formehf repos cpethf buckets cp— les trois sont exactement la même commande. Utilisez celle qui convient le mieux à votre flux de travail.
Pour téléverser un fichier (local → dépôt ou 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/Pour télécharger un fichier (dépôt ou 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.jsonVous pouvez également diffuser vers stdout ou depuis stdin en utilisant - :
# 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.txtPour copier entre deux emplacements sur le 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/Lors de la copie de dossiers entre deux emplacements du Hub, un / final sur le chemin source détermine si le dossier lui-même est imbriqué ou si seuls son contenu sont copiés (style 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/Remarques :
hf cpcopie un seul fichier lorsqu’un chemin local est impliqué. Pour copier des répertoires entiers vers/depuis le local, utilisezhf upload/hf download(dépôts) ouhf buckets sync(buckets).- La copie d'un bucket vers un dépôt n'est pas encore prise en charge.
- La copie locale vers locale n'est pas prise en charge (utilisez
cpde votre shell). - Les copies entre deux emplacements du Hub ne fonctionnent que dans la même zone de stockage.
Synchroniser les répertoires
Utilisez hf buckets sync pour synchroniser des répertoires entre votre machine locale et un bucket. Il compare la source et la destination et ne transfère que les fichiers modifiés.
Pour téléverser un répertoire local vers un bucket :
>>> hf buckets sync ./data hf://buckets/username/my-bucketPour télécharger depuis un bucket vers un répertoire local :
>>> hf buckets sync hf://buckets/username/my-bucket ./dataUtilisez --delete pour supprimer les fichiers de destination qui ne sont pas présents dans la source :
>>> hf buckets sync ./data hf://buckets/username/my-bucket --deleteVous pouvez filtrer les fichiers à synchroniser à l'aide des motifs --include et --exclude :
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"Pour ne mettre à jour que les fichiers existants (en ignorant les nouveaux), utilisez --existing. Pour ne créer que de nouveaux fichiers (en ignorant les existants), utilisez --ignore-existing :
>>> hf buckets sync ./data hf://buckets/username/my-bucket --existing
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existingPour plus de sécurité, vous pouvez générer un plan à examiner avant l'exécution, puis l'appliquer :
# 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.jsonlUtilisez --dry-run pour afficher le plan de synchronisation au format JSONL sur la sortie standard sans rien exécuter. C’est pratique pour l’envoyer en entrée de jq ou d’autres outils :
>>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq .
hf syncest un alias pratique de niveau supérieur pourhf buckets sync. Consultez le guide Buckets pour tous les détails sur les options de synchronisation.
hf models
Utilisez hf models pour lister les modèles sur le Hub et obtenir des informations détaillées sur un modèle spécifique.
Lister les modèles
# 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 10Lorsqu’il est appelé avec un identifiant de modèle, hf models ls liste les fichiers du dépôt de ce modèle :
# 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 mainObtenir les informations du modèle
>>> hf models info Lightricks/LTX-2Utilisez --expand pour récupérer des propriétés supplémentaires telles que downloads, likes, tags, etc.
Obtenir la carte du modèle
Utilisez hf models card pour récupérer la carte du modèle (README) d’un modèle. Par défaut, affiche le contenu complet de la carte sur la sortie standard.
# 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
Utilisez hf datasets pour lister les jeux de données sur le Hub et obtenir des informations détaillées sur un jeu de données spécifique.
Lister les jeux de données
# 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 10Lorsqu’il est appelé avec un identifiant de jeu de données, hf datasets ls répertorie les fichiers du dépôt de ce jeu de données :
# 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 --treeLister un classement de jeux de données
Utilisez hf datasets leaderboard pour afficher les scores des modèles soumis à un jeu de données de référence, afin de trouver les meilleurs modèles pour une tâche ou de comparer des modèles selon leurs scores de référence.
>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified
>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5 --format jsonObtenir les informations du jeu de données
>>> hf datasets info HuggingFaceFW/finewebObtenir la carte du jeu de données
Utilisez hf datasets card pour récupérer la carte du jeu de données (README) d’un jeu de données. Par défaut, affiche le contenu complet de la carte sur la sortie standard.
# 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 --textLister les URL Parquet
Utilisez hf datasets parquet pour découvrir les URL des fichiers parquet d’un jeu de données avant d’écrire des requêtes SQL.
Les jeux de données sur le Hub sont convertis automatiquement en Parquet sur le backend par le service Dataset Viewer (pour les jeux de données éligibles).
Consultez le guide de conversion Parquet pour plus de détails.
>>> 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 sortie de table par défaut inclut le sous-ensemble, la partition et l'URL du fichier parquet depuis l'API du Hub.
Exécuter du SQL sur un parquet de jeu de données
Utilisez hf datasets sql pour exécuter des requêtes SQL brutes avec DuckDB sur les URL parquet des jeux de données.
Découvrez d’abord les URL avec hf datasets parquet, puis interrogez-les directement avec 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 jsonInstallez d'abord DuckDB si nécessaire :
# Python package
>>> pip install duckdb
# or standalone DuckDB CLI (Homebrew: macOS/Linux)
>>> brew install duckdbhf spaces
Utilisez hf spaces pour lister les Spaces sur le Hub et obtenir des informations détaillées sur un Space spécifique.
Lister les Spaces
# List trending Spaces
>>> hf spaces ls
# Search for Spaces
>>> hf spaces ls --search "3d"
# Sort by likes
>>> hf spaces ls --sort likes --limit 10Lorsqu’il est appelé avec un identifiant de Space, hf spaces ls liste les fichiers du dépôt de ce 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 -hObtenir les informations sur l'espace
>>> hf spaces info victor/deepsiteObtenir la carte Space
Utilisez hf spaces card pour récupérer la carte (README) d’un Space. Par défaut, l’intégralité du contenu de la carte est affichée sur la sortie standard.
# 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 --textMettre en pause ou redémarrer un Space détruit son conteneur, de sorte que tout ce qui a été écrit sur le système de fichiers éphémère est perdu. Pour conserver les données entre les redémarrages, montez un Volume ou un bucket avec
hf spaces volumes set(exécutezhf spaces volumes --helppour plus de détails).
Pause a Space
Utilisez hf spaces pause pour mettre un Space en pause lorsque vous ne l'utilisez pas (le temps en pause n'est pas facturé). Relancez-le plus tard avec hf spaces restart.
>>> hf spaces pause username/my-spaceRedémarrer un Space
Utilisez hf spaces restart pour redémarrer un Space. Passez --factory-reboot pour reconstruire le Space de zéro sans utiliser le cache de build.
>>> hf spaces restart username/my-space
>>> hf spaces restart username/my-space --factory-rebootAttendre un Space
Utilisez hf spaces wait pour bloquer jusqu’à ce qu’un Space ait terminé sa construction/démarrage et atteigne un état stable. La commande se termine avec le code 0 si le Space est RUNNING, ou avec un code non nul dans le cas contraire (par exemple BUILD_ERROR). Pratique pour automatiser les scripts après un redémarrage ou un changement de matériel.
>>> 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-spaceLister le matériel disponible
Utilisez hf spaces hardware pour lister toutes les options de matériel disponibles pour Spaces, y compris les tarifs.
>>> hf spaces hardwareVérifiez votre quota ZeroGPU
Utilisez hf spaces zero-gpu quota pour vérifier le solde de votre quota ZeroGPU et la date de sa réinitialisation. Cette commande est pratique pour suivre votre consommation lors de l’appel de Spaces ZeroGPU depuis des scripts, des applications ou des agents.
>>> 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 votre quota est sur le point d’être épuisé, la commande vous suggère d’acheter des crédits depuis vos paramètres de facturation pour continuer à utiliser ZeroGPU au-delà du quota quotidien (réservé aux utilisateurs PRO, Team et Enterprise).
Mettre à jour les paramètres de l'Espace
Utilisez hf spaces settings pour mettre à jour les paramètres d’un Space.
>>> hf spaces settings username/my-space --sleep-time 3600
>>> hf spaces settings username/my-space --hardware t4-medium--sleep-time: durée d'inactivité en secondes avant que le Space ne passe en veille. Utilisez-1pour qu'il ne passe jamais en veille. Disponible uniquement sur le matériel mis à niveau (voir la documentation sur la durée de veille des Spaces).--hardware: type de matériel (par exemplecpu-basic,t4-medium,l4x4). Exécutezhf spaces hardwarepour afficher toutes les options.
Gérer les secrets d’Espace
Utilisez hf spaces secrets ls pour lister les secrets d’un Space, hf spaces secrets add pour ajouter ou mettre à jour un ou plusieurs secrets, et hf spaces secrets delete pour en supprimer un. Passez --secrets-file PATH pour charger les secrets depuis un fichier au format .env. Les clés existantes sont écrasées.
>>> 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 --yesLes valeurs secrètes sont en écriture seule, de sorte que
hf spaces secrets lsaffiche les clés, les descriptions et les horodatages de mise à jour, mais jamais les valeurs secrètes elles-mêmes.
Gérer les variables d’environnement de Space
Utilisez hf spaces variables pour gérer les variables d’environnement non confidentielles sur un Space. Contrairement aux secrets, les variables sont lisibles, de sorte que ls affiche à la fois les clés et les valeurs. Passez --env-file PATH à add pour charger depuis un fichier au format .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 --yesSe connecter à un Space via SSH (Mode Dev)
Utilisez hf spaces ssh pour ouvrir une session SSH dans le conteneur Dev Mode d’un Space. Si le Dev Mode n’est pas activé, le CLI vous demandera de l’activer (ou utilisez --auto pour ignorer la demande).
Votre clé publique SSH doit être enregistrée dans vos paramètres. Consultez la documentation du mode Dev pour plus de détails.
# 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
Utilisez hf papers pour lister, rechercher, obtenir des informations structurées et lire le contenu Markdown des articles sur le Hub.
Liste des articles
# 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=5Rechercher des articles
# 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=jsonObtenir les informations de l'article
# Get structured metadata for a paper (returns JSON)
>>> hf papers info 2601.15621Lire le papier en markdown
# Read the full paper content as markdown
>>> hf papers read 2601.15621hf discussions
Utilisez hf discussions pour gérer les discussions et les pull requests sur les dépôts du Hub directement depuis votre terminal. Vous pouvez lister, afficher, créer, commenter, fermer, rouvrir et fusionner à la fois les discussions et les PR. Pour un guide complet sur le fonctionnement des fonctionnalités communautaires du Hub, consultez le guide des discussions et des pull requests.
Lister les discussions
Pour lister les discussions et les PR ouvertes sur un dépôt, passez l’ID du dépôt à hf discussions list (ou son raccourci hf discussions ls) :
>>> hf discussions list username/my-modelVous pouvez restreindre les résultats par type (discussion ou pull_request), statut (open, closed, merged ou all) ou auteur :
>>> hf discussions list username/my-model --kind pull_request --status merged
>>> hf discussions list username/my-model --author alicePour les scripts, utilisez --format json pour obtenir une sortie structurée, ou --quiet pour n’afficher que les numéros de discussion (un par ligne) :
>>> hf discussions list username/my-model --format json
>>> hf discussions ls username/my-model --quietObtenir les informations d'une discussion ou d'une PR
Pour inspecter une discussion ou une PR spécifique, passez l’ID du dépôt et le numéro de la discussion :
>>> hf discussions info username/my-model 5La sortie contient les métadonnées de la discussion (titre, statut, auteur, etc.) ainsi que la liste complète des événements de la conversation. Pour afficher le diff d’une pull request, utilisez hf discussions diff à la place.
Utilisez --format json pour une sortie lisible par machine, et définissez NO_COLOR=1 pour supprimer les couleurs ANSI lors de l’envoi vers d’autres outils.
Créer une discussion ou une PR
Pour ouvrir une nouvelle discussion, fournissez un titre avec --title. Vous pouvez éventuellement inclure une description en ligne avec --body, ou la charger depuis un fichier avec --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.mdPour créer une pull request plutôt qu’une simple discussion, ajoutez le drapeau --pull-request :
>>> hf discussions create username/my-model --title "Fix typo" --pull-requestCommenter une discussion ou une PR
Ajoutez un commentaire à une discussion ou à une PR existante en spécifiant son numéro. Le corps du commentaire peut être passé en ligne avec --body, lu depuis un fichier avec --body-file, ou transmis via stdin en utilisant --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 -Modifier un commentaire
Modifier un commentaire existant en place en passant le numéro de la discussion et l’ID du commentaire. Les ID de commentaire peuvent être récupérés avec 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.mdJoindre des images et des vidéos
Passez --attach à hf discussions create, comment ou edit pour téléverser un fichier image, vidéo ou audio et l’intégrer au corps du message, comme lorsque vous glissez un fichier dans la zone de commentaire sur le Hub. Si le corps du message référence déjà le fichier, comme dans , la référence pointe vers le fichier téléversé. Sinon, le fichier est ajouté à la fin du corps du message. Pour définir le texte alternatif d’une image ajoutée, ajoutez-le après 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.mp4Les formats pris en charge sont PNG, JPEG, GIF, WebP, MP4, MOV, WebM, MP3 et WAV, jusqu'à 10 Mo (50 Mo pour les vidéos).
Fermer, rouvrir et fusionner
Vous pouvez fermer une discussion ou une PR avec hf discussions close. Par défaut, une demande de confirmation s’affiche. Passez --yes pour ignorer cette demande, et --comment pour laisser un message de clôture :
>>> hf discussions close username/my-model 5
>>> hf discussions close username/my-model 5 --yes --comment "Resolved"Pour rouvrir une discussion précédemment fermée, utilisez hf discussions reopen :
>>> hf discussions reopen username/my-model 5 --yesPour fusionner une pull request, utilisez hf discussions merge :
>>> hf discussions merge username/my-model 5 --yesRenommer et diff
Vous pouvez renommer une discussion en fournissant le nouveau titre :
>>> hf discussions rename username/my-model 5 "Updated title"Pour afficher la diff d'une pull request directement dans votre terminal, utilisez hf discussions diff :
>>> hf discussions diff username/my-model 5hf repos
hf repos permet de lister, créer, dupliquer, supprimer et déplacer des dépôts, de mettre à jour leurs paramètres et de supprimer des fichiers sur le Hugging Face Hub. Il inclut également des sous-commandes pour gérer les branches et les tags.
Lister les dépôts
Utilisez hf repos ls pour lister tous vos dépôts (modèles, jeux de données, espaces et buckets) avec les informations de stockage, triés par utilisation du stockage. Par défaut, seuls les 30 premiers dépôts sont affichés :
# 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.Filtrez par type de dépôt, recherchez par nom ou ajustez la limite :
# 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 0Utilisez --format json pour les scripts ou -q pour les ID uniquement. Lors de l’utilisation d’un tube, utilisez --limit 0 pour exporter tous les dépôts :
>>> hf repos ls --limit 0 --format json | jq '.[].id'
>>> hf repos ls -qCréer un dépôt
>>> 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-modelCréer un jeu de données ou un Space privé :
>>> hf repos create my-cool-dataset --repo-type dataset --private
>>> hf repos create my-gradio-space --repo-type space --sdk gradioUtilisez --exist-ok si le dépôt peut déjà exister, et --resource-group-id pour cibler un groupe de ressources Enterprise.
Créer un dépôt dans une région spécifique :
>>> hf repos create my-model --region usDupliquer un dépôt
Utilisez hf repos duplicate pour copier un modèle, un jeu de données ou un Space existant vers votre compte (ou vers une organisation). La copie est effectuée sur le serveur et conserve l’historique git :
>>> hf repos duplicate openai/gdpval --type dataset
>>> hf repos duplicate openai/gdpval myorg/my-gdpval --type dataset --privateLes fichiers LFS/Xet du nouveau dépôt peuvent encore être copiés en arrière-plan après le retour de la commande. Dans ce cas, un avertissement est affiché et le téléchargement de ces fichiers depuis le nouveau dépôt peut échouer jusqu'à la fin de la copie.
Supprimer un dépôt
>>> hf repos delete Wauplin/my-cool-modelJeux de données et Spaces :
>>> hf repos delete my-cool-dataset --repo-type dataset
>>> hf repos delete my-gradio-space --repo-type spaceDéplacer un dépôt
>>> hf repos move old-namespace/my-model new-namespace/my-modelMettre à jour les paramètres du dépôt
>>> 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: l'un deauto,manual,false--private true|false: définir la confidentialité du dépôt
Supprimer des fichiers d’un dépôt
La sous-commande hf repos delete-files <repo_id> permet de supprimer des fichiers d’un dépôt. Voici quelques exemples d’utilisation.
Supprimer un dossier :
>>> hf repos delete-files Wauplin/my-cool-model folder/
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Supprimer plusieurs fichiers :
>>> 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...Utilisez des motifs génériques pour supprimer des ensembles de fichiers. Les motifs sont des wildcards standard (motifs globbing) documentés ici. L’appariement des motifs est basé sur fnmatch.
Notez que
fnmatchassocie*à travers les limites de chemin, contrairement au globbing des shells Unix traditionnels. Par exemple,"data/*.json"correspond à la fois àdata/file.jsonet àdata/subdir/file.json. Pour ne correspondre qu'aux fichiers du répertoire immédiat, vous devez les lister explicitement ou utiliser des motifs plus spécifiques.
>>> hf repos delete-files Wauplin/my-cool-model "*.txt" "folder/*.bin"
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Pour supprimer des fichiers d’un dépôt, vous devez être authentifié et autorisé. Par défaut, le jeton enregistré localement (à l’aide de hf auth login) est utilisé. Si vous souhaitez vous authentifier explicitement, utilisez l’option --token :
>>> hf repos delete-files --token=hf_**** Wauplin/my-cool-model file.txthf repos branch
Utilisez hf repos branch pour créer et supprimer des branches pour les dépôts sur le 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 devToutes les commandes acceptent
--repo-type(l'un desmodel,dataset,space) et--tokensi vous devez vous authentifier explicitement. Utilisez--helpsur n'importe quelle commande pour voir toutes les options.
hf cache
Utilisez hf cache pour gérer votre répertoire de cache local Hugging Face. Le cache stocke les modèles, les jeux de données, les Spaces et les noyaux téléchargés depuis le 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
Utilisez hf cache ls pour inspecter ce qui est stocké localement dans votre cache Hugging Face. Par défaut, il agrège les informations par dépôt :
>>> 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.Ajoutez --revisions pour affiner la recherche vers des instantanés spécifiques, et enchaînez les filtres pour vous concentrer sur l’essentiel :
>>> 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.La commande prend en charge plusieurs formats de sortie pour l'automatisation : --format json affiche des objets structurés, --format csv écrit des lignes séparées par des virgules, et --quiet n'affiche que les identifiants. Utilisez --sort pour trier les entrées par accessed, modified, name ou size (ajoutez :asc ou :desc pour contrôler l'ordre), et --limit pour limiter les résultats aux N premières entrées. Combinez ces options avec --cache-dir pour cibler des emplacements de cache alternatifs. Consultez le guide Gérer votre cache pour les flux de travail avancés.
Supprimez les entrées de cache sélectionnées avec hf cache ls --q en transmettant les identifiants à 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 supprime les dépôts mis en cache, des révisions individuelles ou des fichiers uniques. Passez un ou plusieurs identifiants de dépôt (model/bert-base-uncased), des URI hf:// ou des hachages de révision :
>>> 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.Les URI hf:// au niveau du dépôt sont également prises en charge :
>>> 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.Pour supprimer un fichier unique plutôt qu’un dépôt entier, par exemple une quantification GGUF, passez un URI de fichier hf://. Le fichier est supprimé de toutes les révisions mises en cache du dépôt, et son blob n’est supprimé que si aucun autre fichier mis en cache ne le référence encore :
>>> 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 révision reste utilisable, et un fichier supprimé est à nouveau téléchargé la prochaine fois qu’il est nécessaire. Les chemins doivent correspondre exactement : les dossiers et les motifs glob ne sont pas pris en charge, et les cibles de fichiers ne peuvent pas être mélangées avec des dépôts ou des révisions dans le même appel.
Mélangez des dépôts et des révisions spécifiques dans le même appel. Utilisez --dry-run pour prévisualiser l’impact, ou --yes pour passer la demande de confirmation — pratique dans les scripts automatisés :
>>> 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.Lorsque vous travaillez hors de l'emplacement de cache par défaut, associez la commande à --cache-dir PATH.
hf cache prune
hf cache prune est un raccourci pratique qui libère l’espace occupé par les déchets du cache : toutes les révisions détachées (non référencées) (en ne conservant que les révisions encore accessibles via une branche ou un tag), les fichiers .incomplete résiduels issus de téléchargements interrompus, ainsi que les blobs partagés non plus référencés par aucun dépôt en cache :
>>> 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.Les fichiers .incomplete sont des téléchargements partiels laissés derrière eux lorsqu’un téléchargement est interrompu. Ils ne sont pas suivis par hf cache ls/rm (qui fonctionnent au niveau de la révision), de sorte que hf cache ls les signale avec un indice et que hf cache prune les supprime automatiquement.
Comme pour les autres commandes de cache, --dry-run, --yes et --cache-dir sont disponibles. Consultez le guide Gérer votre cache pour plus d’exemples.
hf cache verify
Utilisez hf cache verify pour valider les fichiers locaux par rapport à leurs sommes de contrôle sur le Hub. Vous pouvez vérifier soit un instantané de cache, soit un répertoire local classique.
Exemples :
# 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/repoPar défaut, la commande émet des avertissements concernant les fichiers manquants ou superflus. Utilisez des drapeaux pour convertir ces avertissements en erreurs :
>>> hf cache verify deepseek-ai/DeepSeek-OCR --fail-on-missing-files --fail-on-extra-filesEn cas de succès, vous verrez un récapitulatif :
✅ 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 des incohérences sont détectées, la commande affiche une liste détaillée et se termine avec un statut non nul.
hf repos tag
Utilisez hf repos tag pour créer, lister et supprimer des étiquettes pour les dépôts sur le 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.0Étiqueter un modèle
Pour étiqueter un dépôt, vous devez fournir l'repo_id et le nom de l'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-modelÉtiqueter un modèle à une révision spécifique
Si vous souhaitez étiqueter une révision spécifique, vous pouvez utiliser l'option --revision. Par défaut, l'étiquette sera créée sur la branche 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-modelÉtiqueter un jeu de données ou un Space
Si vous souhaitez étiqueter un jeu de données ou un Space, vous devez spécifier l’option --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-stackListe des tags
Pour lister tous les tags d’un dépôt, utilisez la sous-commande list (ou 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.1Supprimer un tag
Pour supprimer un tag, utilisez la sous-commande 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-modelVous pouvez également passer -y pour ignorer l'étape de confirmation.
hf env
La commande hf env affiche les détails de la configuration de votre machine. Cela est utile lorsque vous ouvrez un ticket sur GitHub pour aider les mainteneurs à investiguer votre problème.
>>> 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
Exécutez des tâches de calcul sur l’infrastructure Hugging Face avec une interface familière, semblable à Docker.
hf jobs est un outil en ligne de commande qui vous permet d’exécuter n’importe quoi sur l’infrastructure de Hugging Face (y compris des GPU et des TPU !) avec de simples commandes. Pensez à docker run, mais pour exécuter du code sur des A100.
Pour un aperçu général des Jobs et de la tarification, consultez la documentation Hub Jobs. Pour l'utilisation de l'API Python en complément de la CLI, consultez le guide d'exécution et de gestion des 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.pyLes Hugging Face Jobs sont disponibles pour tout utilisateur ou toute organisation disposant de crédits prépayés.
Démarrage rapide
1. Lancer votre premier job
# Run a simple Python script
>>> hf jobs run python:3.12 python -c 'print("Hello from HF compute!")'Cette commande exécute le job et affiche les journaux. Vous pouvez passer --detach pour exécuter le Job en arrière-plan et n’afficher que l’identifiant du Job. Ajoutez -q pour afficher uniquement l’identifiant du Job, ce qui est pratique pour le capturer dans un script :
>>> JOB_ID=$(hf jobs run -dq python:3.12 python train.py)
>>> hf jobs wait "$JOB_ID"2. Vérifier l'état du travail
# 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 waitLes commandes hf jobs run et hf jobs wait non détachées se terminent avec un code non nul si un Job échoue, ce qui permet d’enchaîner les commandes avec && :
>>> hf jobs run python:3.12 python train.py && echo "training succeeded"3. Exécuter sur GPU
Vous pouvez également exécuter des tâches sur des GPU ou des TPU à l'aide de l'option --flavor. Par exemple, pour exécuter une tâche PyTorch sur un 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()}")'L'exécution de ce code affichera la sortie suivante !
This code ran with the following GPU: NVIDIA A10G
Utilisez -- pour séparer les options de Jobs des arguments transmis à votre commande ou à votre script.
Jobs n’interprète pas les options situées après --.
>>> hf jobs run --flavor cpu-basic python:3.12 -- python --helpC’est tout ! Vous exécutez désormais du code sur l’infrastructure de Hugging Face.
Cas d'utilisation courants
- Entraînement de modèles : Ajustez finement ou entraînez des modèles sur des GPU (T4, A10G, A100) sans gérer l'infrastructure
- Génération de données synthétiques : générer des jeux de données à grande échelle à l'aide de LLM sur du matériel puissant
- Prétraitement des données : Traitez des jeux de données massifs avec des configurations à forte puissance CPU pour des charges de travail parallèles
- Inférence par lots : Exécuter une inférence hors ligne sur des milliers d'échantillons à l'aide de configurations GPU optimisées
- Expériences et benchmarks : Exécutez des expériences ML sur un matériel cohérent pour des résultats reproductibles
- Développement et débogage : Testez le code GPU sans configuration CUDA locale
Passer les variables d’environnement et les secrets
Vous pouvez passer des variables d'environnement à votre tâche à l'aide de
# 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"])'Les secrets sont chiffrés côté serveur dans les trois formes. -s MY_SECRET=psswrd fonctionne également, mais la valeur se retrouve alors dans l’historique de votre shell et dans la liste des processus (/proc/<pid>/cmdline sur Linux), ce qui provoque l’affichage d’un avertissement sur stderr par le CLI lorsque vous l’utilisez ; réservez cette forme aux valeurs qui ne sont pas réellement sensibles. La même règle s’applique à --token <value> : préférez hf auth login ou la variable d’environnement HF_TOKEN. Un fichier d’environnement ou de secrets doit être lisible uniquement par vous (chmod 600) — le CLI émet un avertissement si ce n’est pas le cas.
Utilisez
--secrets HF_TOKENpour transmettre votre jeton Hugging Face local de manière implicite. Avec cette syntaxe, le secret est récupéré depuis la variable d’environnement. PourHF_TOKEN, il peut lire le fichier de jeton situé dans le dossier d’accueil Hugging Face si la variable d’environnement n’est pas définie.
Variables d'environnement intégrées
À l'intérieur du conteneur de tâche, les variables d'environnement suivantes sont automatiquement disponibles :
| Variable | Description |
|---|---|
JOB_ID | L'identifiant unique du travail actuel. Utilisez-le pour référencer le travail de manière programmatique. |
ACCELERATOR | Le type d'accélérateur disponible (par exemple, t4-medium, a10g-small, a100x4). Vide si aucun accélérateur. |
CPU_CORES | Le nombre de cœurs CPU disponibles pour le travail (par exemple, 2, 4, 8). |
MEMORY | La quantité de mémoire disponible pour le travail (par exemple, 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\")}')"Délai d'expiration de la tâche
Les jobs ont un délai d'expiration par défaut de 30 minutes, après lequel ils s'arrêtent automatiquement. Pour les tâches de longue durée comme l'entraînement de modèles, définissez un délai d'expiration personnalisé à l'aide de l'option --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 supportedL'option --timeout fonctionne également avec les scripts UV et les tâches planifiées :
# 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 votre dépassement dépasse le délai d'expiration, il sera automatiquement terminé. Définissez toujours un délai d'expiration approprié avec une marge de sécurité pour les tâches de longue durée afin d'éviter les terminaisons inattendues de tâches.
Réessayer et relancer un Job
--attempts définit le nombre maximal de tentatives, y compris la première exécution. Il fonctionne avec Docker, UV et les Jobs planifiés. Relancer un Job démarre un nouveau Job avec la même spécification enregistrée :
>>> hf jobs run --attempts 3 --detach python:3.12 python train.py
>>> hf jobs rerun <job_id>Un nombre de tentatives de 3 permet jusqu’à deux nouvelles tentatives en cas d’échec d’un Job. hf jobs rerun réutilise également le nombre de tentatives d’origine. Comme hf jobs run, il affiche les journaux du nouveau Job en continu jusqu’à sa fin. Utilisez --detach pour revenir immédiatement.
Matériel
Options --flavor disponibles :
- 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
(mis à jour en 07/2025 à partir des docs suggested_hardware de Hugging Face)
Volumes
Montez un volume sur le disque du Job à l’aide de -v ou --volume.
Vous pouvez monter n'importe quel dépôt Hugging Face (modèle/jeu de données/espace) ou Storage Bucket à l'aide du schéma d'URL hf://. Par exemple :
- monter un dépôt de modèle :
-v hf://openai/gpt-oss-120b:/model - monter un dépôt de jeu de données :
-v hf://datasets/HuggingFaceFW/fineweb:/data - monter un bucket de stockage :
-v hf://buckets/username/my-bucket:/mnt - monter un espace :
-v hf://spaces/username/my-space:/app - monter un sous-dossier dans un dépôt :
-v hf://datasets/org/ds/train:/data
Vous pouvez ensuite utiliser le volume monté comme un répertoire 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 ...Les modèles, les jeux de données et les espaces sont toujours montés en lecture seule. Les buckets de stockage sont en lecture + écriture par défaut — ce qui est particulièrement utile pour les données qui changent fréquemment, car les fichiers peuvent être écrasés ou supprimés sur place.
Utilisez :ro pour activer le mode lecture seule :
- monter un bucket de stockage en lecture seule :
-v hf://buckets/username/my-bucket:/mnt:ro
Monter des données locales
Le côté source de -v peut également être un répertoire local. Il est d'abord synchronisé avec votre Storage Bucket jobs-artifacts et le dossier de bucket résultant est monté dans le Job :
>>> hf jobs uv run -v ./my-data:/data process.pyLa réexécution de la commande ne téléverse que les nouveaux fichiers ou les fichiers modifiés. Les répertoires locaux sont montés en lecture seule par défaut. Utilisez :rw pour autoriser le Job à écrire sur le volume, par exemple pour récupérer les sorties après la fin du Job (un répertoire local vide fonctionne également) :
>>> 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-outÉtiquettes
Ajoutez des étiquettes à un Job à l’aide de -l ou --label. Les étiquettes sont des paires clé=valeur qui appliquent des métadonnées à un Job. Pour étiqueter un Job avec deux étiquettes, répétez le drapeau d’étiquette (-l ou --label) :
>>> hf jobs run -l my-label --label foo=bar ubuntu echo "This Job has multiple labels"La clé my-label ne spécifie pas de valeur, sa valeur est donc par défaut une chaîne vide ("").
Utilisez --name pour ajouter l'étiquette name lors de la création d'un Job. Les noms facilitent la recherche et l'identification des Jobs dans l'interface ; ils sont facultatifs et n'ont pas besoin d'être uniques. Si vous ne passez pas --name, un nom est dérivé automatiquement de l'image Docker ou du script, ainsi que d'un court hachage de la commande et des paramètres d'exécution résolus (flavor, timeout, valeurs d'environnement, …), de sorte que la même configuration produit toujours le même nom (par ex. python:3.12 foo --truc → python-3-12-1a2b3c4d). Modifier un paramètre modifie le nom, même si la commande reste identique. Vous pouvez également renommer un Job existant :
>>> hf jobs run --name training-v2 python:3.12 python train.py
>>> hf jobs labels <job_id> --name training-v2Utilisez --status, --label et --name dans hf jobs ls pour filtrer les Jobs. --status accepte un ou plusieurs statuts, --label accepte des paires key=value, et --name est un raccourci pour --label name=NAME. Un Job doit correspondre à tous les filtres pour être listé. Le nom du Job est également affiché dans sa propre colonne 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=mlPar défaut, hf jobs ps affiche au maximum 100 Jobs afin d’éviter de surcharger le terminal. Utilisez --limit pour modifier cette valeur, ou --limit 0 pour tous les afficher :
# Show up to 500 Jobs
>>> hf jobs ps -a --limit 500
# Show all Jobs (no limit)
>>> hf jobs ps -a --limit 0Exposer les ports du Job
Utilisez --expose pour un port protégé par jeton et --expose-public pour un port qui doit autoriser un accès non authentifié. Les deux drapeaux peuvent être répétés et combinés, et fonctionnent avec Docker, UV et les Jobs planifiés.
# 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 prend les ports protégés par jeton comme arguments positionnels et les ports publics avec --public. Il applique la modification sans relancer le Job. Les ports omis de la liste de remplacement sont fermés.
Se connecter à un Job via SSH
Passez --ssh à hf jobs run (ou hf jobs uv run) pour rendre le conteneur du Job accessible via SSH, puis connectez-vous avec 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_ed25519Seuls les utilisateurs disposant d'un accès en écriture à l'espace de noms du Job (le créateur du Job ou les membres de l'organisation propriétaire) sont autorisés à y accéder, authentifiés par une clé publique SSH enregistrée sur https://huggingface.co/settings/keys.
Groupes de réseaux
Passez --network-group <name> à hf jobs run (ou hf jobs uv run) pour permettre aux Jobs du même espace de noms et du même groupe de ressources de se joindre sur tous les ports. Au sein de chaque membre, $HF_NETWORK_GROUP_HOSTNAME se résout vers tous les Jobs du groupe, et ${HF_NETWORK_GROUP_PREFIX}<alias> vers les membres qui ont réclamé un alias avec --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/"'Les membres sont résolubles avant d’être prêts, il est donc recommandé d’établir la connexion avec des tentatives répétées. Les noms de groupe et les alias sont des chaînes alphanumériques minuscules et des tirets, avec un maximum de 46 et 34 caractères respectivement.
Scripts UV (expérimental)
Exécuter des scripts UV (scripts Python avec des dépendances intégrées) sur l’infrastructure HF. Les scripts UV sont des scripts Python qui incluent leurs dépendances directement dans le fichier à l’aide d’une syntaxe de commentaire spéciale.
# 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'Les scripts UV sont des scripts Python qui incluent leurs dépendances directement dans le fichier à l’aide d’une syntaxe de commentaire spéciale. Ils sont donc parfaits pour les tâches autonomes qui ne nécessitent pas de configuration de projet complexe. En savoir plus sur les scripts UV dans la documentation UV.
Utilisez -- pour transmettre des options conflictuelles à votre script. Ici, --help est transmis à train.py au lieu d’afficher l’aide de Jobs :
>>> hf jobs uv run --flavor t4-small train.py -- --helpCela s’applique également aux drapeaux de formatage : hf jobs run, hf jobs uv run et leurs variantes scheduled consomment --format, --json et -q où qu’ils apparaissent, utilisez donc -- lorsque votre script en a besoin.
Inclure la configuration de lancement avec le script
Certains scripts ne s’exécutent correctement que sur un environnement d’exécution spécifique : une image donnée, un type de GPU, un interpréteur système, etc. Un script peut transporter cette configuration avec lui dans un tableau facultatif [tool.hf-jobs] dans son en-tête 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 lance ensuite le script avec le runtime approprié, au lieu de l’exécuter silencieusement sur une image CPU avec l’interpréteur incorrect. Le tableau est invisible pour un simple uv run : les tableaux [tool.*] font partie de PEP 723 et les outils ignorent ceux qui ne leur appartiennent pas.
Clés prises en charge, toutes facultatives : image, flavor, python, timeout, name, namespace, env, secrets, labels, volumes, network_group et network_aliases. Elles correspondent aux drapeaux du même nom (name est stocké en tant que libellé name, volumes accepte les mêmes spécifications hf://...:/MOUNT_PATH que -v, network_aliases est une liste de valeurs --network-alias). Une clé inconnue est une erreur plutôt qu'une intention silencieusement ignorée — une faute de frappe comme flavour est précisément l'échec que cette fonctionnalité vise à prévenir.
Toutes les valeurs doivent être des chaînes de caractères, y compris les valeurs de env et labels : -e BATCH_SIZE=64 se traduit par env = { BATCH_SIZE = "64" }, et non par env = { BATCH_SIZE = 64 } (TOML interprète cette dernière comme un entier et le tableau est rejeté). La seule exception est timeout, qui accepte également un nombre entier de secondes (timeout = 7200 est équivalent à timeout = "2h").
Les valeurs du script sont des valeurs par défaut : un indicateur explicite l’emporte toujours, et env, secrets, labels et volumes sont fusionnés entrée par entrée, de sorte que -e et -v peuvent compléter ce que le script déclare :
# 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 fait exception : les alias qu’un Job revendique forment un ensemble, de sorte que --network-alias remplace la liste du script au lieu de s’y ajouter. Les Jobs planifiés n’ont aucun groupe réseau, aussi hf jobs scheduled uv run rejette un script qui déclare network_group ou network_aliases.
secrets only lists secret names: values always come from the environment of whoever runs the script, never from the script itself (HF_TOKEN also resolves from hf auth login). A secret that is requested but not set locally is an error, rather than a Job silently receiving an empty value. With --dry-run it is shown as <not set> instead, so that the configuration of a script whose secrets are not provisioned yet remains visible.
Chaque exécution renvoie la configuration soumise, en marquant les valeurs provenant du script. Utilisez --dry-run pour l’afficher sans rien lancer :
>>> 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.Cela fonctionne également pour les scripts situés derrière une URL : le script est téléchargé une seule fois lors de la soumission du Job (pour lire son en-tête) et transmis au Job comme un script local, au lieu d’être à nouveau téléchargé par le conteneur. L’URL doit être accessible depuis votre machine. Comme les scripts locaux, les scripts URL utilisent le montage d’artefacts réservé
/data; utilisez un autre chemin de montage pour vos volumes d’entrée.
Pour hf jobs scheduled uv run, cela fixe le script à son contenu au moment de la création. La mise à jour de l’URL source ne modifie plus les exécutions futures : recréez le Job planifié pour prendre en compte une nouvelle version.
--dry-run est également disponible sur hf jobs run, hf jobs scheduled run et hf jobs scheduled uv run. Il ignore la soumission et les téléversements de volumes locaux. Les noms générés automatiquement pour les Jobs Docker et UV incluent la configuration de lancement résolue, de sorte que toute modification des paramètres d’exécution ou des valeurs d’environnement modifie le nom.
hf jobs scheduled
Planifiez et gérez les tâches qui s'exécuteront sur l'infrastructure HF.
L'horaire doit être l'un des @annually, @yearly, @monthly, @weekly, @daily, @hourly, ou une expression d'horaire CRON (par exemple, "0 9 * * 1" pour 9 h chaque lundi).
# 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.pyUtilisez les mêmes paramètres que hf jobs run pour transmettre des variables d'environnement, des secrets, un délai d'expiration, etc.
Gérer les tâches planifiées à l'aide de
# 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 démarre des machines cloud isolées basées sur Jobs : créez-en une, exécutez des commandes avec un affichage en direct de la sortie, et copiez des fichiers à l’intérieur et à l’extérieur. Toute image Docker disposant de /bin/sh fonctionne. Consultez le guide des Sandboxes pour l’API Python, et le guide conceptuel pour comprendre son fonctionnement en profondeur.
Les sandboxes sont expérimentales, et leur API et leur comportement peuvent changer sans préavis. Les sandboxes partagées sont destinées aux charges de travail au sein de la même frontière de confiance ; utilisez une sandbox dédiée pour les charges de travail qui ne se font pas confiance mutuellement.
# 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 687f911eaea852de79c4a50aUtilisez --flavor pour choisir le matériel (par exemple a10g-small) , --idle-timeout pour limiter la durée de vie du bac à sable, et -l / --label pour associer des étiquettes à son Job. Pour déployer de nombreux bacs à sable CPU peu coûteux, préparez un pool avec hf sandbox pool create et créez-y des instances avec hf sandbox create --pool <id> (voir le guide des bacs à sable).
Passer des variables d’environnement et des secrets à un bac à sable
Il existe deux canaux distincts, avec des propriétés de stockage différentes :
| channel | flags | bac à sable dédié | bac à sable mutualisé (--pool) |
|---|---|---|---|
| environnement | -e / --env, --env-file | stockées dans les métadonnées du job | fournis à l'hôte lors de la création, et non stockés dans les métadonnées du job |
| secrets | -s / --secrets, --secrets-file | chiffrement côté serveur | non disponible — utilisez --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 fonctionne également, mais la valeur est enregistrée dans l’historique de votre shell et dans la liste des processus, ce qui provoque un avertissement de la CLI sur stderr, y compris en mode silencieux. Les sandbox en pool rejettent --secrets catégoriquement : une pool ne dispose pas de canal de secrets chiffrés, et hf sandbox create --pool <id> -s KEY=value renvoie une erreur avec un renvoi vers --env.
hf webhooks
hf webhooks vous permet de gérer les webhooks sur le Hugging Face Hub directement depuis le terminal. Les webhooks vous permettent d’écouter des événements (pushes, discussions, etc.) sur des dépôts, des utilisateurs ou des organisations et de déclencher des actions — soit en envoyant une requête à une URL distante, soit en exécutant un Job sur l’infrastructure de Hugging Face.
Liste des 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:HuggingFaceUtilisez --format json pour une sortie lisible par machine, ou -q pour n’afficher que les identifiants :
>>> hf webhooks ls --format json
>>> hf webhooks ls -qObtenir les informations du webhook
>>> hf webhooks info wh-abc123Affiche les détails complets du webhook au format JSON.
Créer un webhook
Créer un webhook qui envoie des charges utiles à une 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 repoOu créez un webhook qui déclenche un Job à la place :
>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-cLes secrets du Job source ne sont pas copiés vers le webhook. Utilisez --secrets ou --secrets-file (même syntaxe que hf jobs run) pour les transmettre au Job déclenché. Par exemple, --secrets HF_TOKEN transmet votre jeton Hugging Face local :
>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch bucket:my-org/my-bucket --secrets HF_TOKENL’option --watch utilise le format type:name où type est l’un des éléments suivants : model, dataset, space, bucket, org ou user. Elle peut être répétée pour surveiller plusieurs éléments. Utilisez --domain pour filtrer les événements sur repo ou discussion, et --secret pour définir un secret de signature.
Mettre à jour un webhook
>>> hf webhooks update wh-abc123 --url https://new-url.com/hook
>>> hf webhooks update wh-abc123 --watch model:gpt2 --domain repoSeules les options fournies sont modifiées. Notez que --watch remplace l'intégralité de la liste surveillée lorsqu'il est spécifié.
Pour mettre à jour les secrets d’un webhook déclenché par un Job, passez --job-id avec --secrets. Les secrets listés remplacent les valeurs stockées et tous les autres secrets sont conservés :
>>> hf webhooks update wh-abc123 --job-id 687f911eaea852de79c4a50a --secrets HF_TOKENActiver / désactiver un webhook
>>> hf webhooks enable wh-abc123
>>> hf webhooks disable wh-abc123Supprimer un webhook
>>> hf webhooks delete wh-abc123
Are you sure you want to delete webhook 'wh-abc123'? [y/N]: y
Webhook deleted: wh-abc123Utilisez --yes pour ignorer la demande de confirmation :
>>> hf webhooks delete wh-abc123 --yesToutes les commandes acceptent
--tokenpour remplacer l'authentification. Utilisez--helpsur n'importe quelle commande pour afficher toutes les options.
hf endpoints
Utilisez hf endpoints pour lister, déployer, décrire et gérer les Inference Endpoints directement depuis le terminal. L’alias hf inference-endpoints reste disponible pour des raisons de compatibilité.
# 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 --yesAjoutez
--namespacepour cibler une organisation et--tokenpour remplacer l’authentification.
Trouver du matériel pour le déploiement
hf endpoints deploy nécessite cinq drapeaux matériels (--vendor, --region, --accelerator, --instance-type et --instance-size). hf endpoints hardware liste les combinaisons valides, avec le prix par réplique et par heure en USD et le quota d'accélérateurs de votre espace de noms :
>>> 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 x1Les drapeaux de filtre sont les drapeaux de déploiement (--vendor, --region, --accelerator, --instance-type), de sorte que ce sur quoi vous filtrez est ce que vous passez à deploy. Seuls les matériels sur lesquels vous pouvez déployer actuellement sont listés : un statut utilisable, et suffisamment de quota d'accélérateurs restant dans votre espace de noms pour une réplique. Ajoutez --all pour voir également ce qui est obsolète, temporairement indisponible ou hors quota. --format json ajoute les spécifications restantes par réplique (vCPUs, architecture, nombre d'accélérateurs) à chaque entrée.
Le quota est défini par espace de noms et détermine quelles lignes sont affichées. Si vous déployez au sein d’une organisation, passez le même
--namespaceque celui que vous passerez àdeploy— sinon, vous consultez votre quota personnel, ce qui peut à la fois masquer du matériel sur lequel l’organisation peut déployer et afficher du matériel sur lequel elle ne peut pas.
Déployer un conteneur personnalisé
Pour déployer votre propre image Docker plutôt qu’une image gérée par Hugging Face, passez --framework custom avec --custom-image. Le dépôt du modèle est monté à /repository dans le conteneur. Utilisez --container-args (et éventuellement --container-command) pour passer une chaîne de lancement entre guillemets, --env/--secrets pour injecter des variables d’environnement, et --type pour définir le type d’accès (public, authenticated ou 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 et --container-command ne sont pas limités aux images personnalisées : ils correspondent à model.args et model.command dans la charge utile de l’API, qui s’appliquent également aux images gérées. Sur un endpoint existant, les deux drapeaux remplacent la valeur actuelle au lieu de s’y ajouter ; passez donc la liste complète souhaitée et utilisez une chaîne vide pour l’effacer. Les endpoints déployés depuis le catalogue sont déjà fournis avec des drapeaux moteur optimisés ; vérifiez donc hf endpoints describe avant de les écraser :
>>> hf endpoints update my-endpoint \
--container-args "--enable-auto-tool-choice --tool-call-parser lfm2"Déployer une image de moteur gérée
--custom-image seul déploie un conteneur arbitraire. Ajoutez --engine pour l’exécuter en tant que l’un des moteurs gérés par l’API (vllm, sglang, tgi, tei, llamacpp, hf-serve, …), ce qui active les paramètres de ce moteur, notamment --tensor-parallel-size et --data-parallel-size. vLLM et SGLang utilisent par défaut un seul accélérateur, tandis que le point de terminaison reçoit tous les accélérateurs de son instance ; laisser les deux paramètres non définis chargerait donc le modèle sur un seul accélérateur et laisserait les autres inactifs, tout en signalant un état sain. C’est pourquoi l’API rejette désormais cette configuration :
>>> 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 8Ce n’est pas la même chose que --container-args "... --tp 8" ci-dessus : --tensor-parallel-size écrit dans la configuration model.image du moteur, qui est ce que l’API valide par rapport au nombre d’accélérateurs de l’instance, tandis que --container-args n’ajoute qu’un drapeau à la ligne de commande. Utilisez --container-args pour les drapeaux du moteur sans champ d’image, et pour les conteneurs personnalisés simples, qui n’ont pas de champs de parallélisme.
Pour retuner un point de terminaison en cours d’exécution, passez les tailles séparément. model.image est envoyé en entier et nécessite url, l’image actuelle du point de terminaison est donc récupérée et mise à jour sur place :
>>> hf endpoints update gpt-oss-120b-vllm --tensor-parallel-size 4 --data-parallel-size 2hf endpoints update accepte également --custom-image et --engine, la seule manière de modifier l’image d’un endpoint depuis le CLI. Ce chemin remplace model.image au lieu de le mettre à jour partiellement, il est donc recommandé d’exécuter d’abord hf endpoints describe et de renvoyer les éléments que vous souhaitez conserver.
catalogue des endpoints hf
Utilisez hf endpoints catalog pour interagir avec le catalogue de modèles Inference Endpoints. Déployez des modèles directement depuis le catalogue avec des configurations optimisées.
Chaque modèle du catalogue est accompagné d’une ou plusieurs recettes : une combinaison matériel et moteur testée pour ce modèle. hf endpoints catalog ls affiche une ligne par recette, de sorte qu’un modèle disposant à la fois d’une recette GPU et d’une recette Neuron apparaît deux fois :
# 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 et --limit filtrent tous côté serveur.
# 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-endpointAvec --repo, la recette par défaut peut être affinée à l'aide de --accelerator (cpu, gpu, neuron) et de --gguf-file (pour les modèles qui disposent d'une recette par quantification). Les deux sont rejetés en présence de --recipe, qui désigne déjà une recette unique.