Installing and updating 13
Command What it does
curl -LsSf https://hf.co/cli/install.sh | bashInstall on macOS or Linux Standalone installer, the method the guide recommends; it also installs the hf-cli skill for AI agents.
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"Install on Windows Runs the same standalone installer from PowerShell.
curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skillInstall without the agent skill Skips the global hf-cli skill that the installer otherwise adds for Claude Code and similar agents.
pip install -U "huggingface_hub"Install or upgrade with pip The hf command ships inside the core Python package, so no extra is needed.
brew install hfInstall with Homebrew
uvx hf auth loginRun a command without installing uvx runs the latest release in an isolated environment each time, with nothing installed permanently.
hf updateUpdate the CLI Detects whether hf came from Homebrew, the standalone installer or pip and runs the matching upgrade.
hf --helpList commands and global options The same flag after any command, such as hf upload, prints the options of that command.
hf upload --helpShow one command's options
hf versionPrint the CLI version
hf envPrint environment details Output lists library version, platform, token path and cache settings, ready to paste into a GitHub issue.
hf --install-completionInstall shell completion Sets up tab completion for the shell you are running.
hf --show-completionPrint the completion script Prints the script without installing it, so it can be copied or customised.
Agent skills and extensions 10
Command What it does
hf skills addInstall the hf-cli agent skill Adds the skill to the current project so coding agents that read .agents/skills learn the hf commands.
hf skills add --globalInstall the skill for all projects Installs at user level rather than inside the project directory.
hf skills add huggingface-gradio --dest=~/my-skillsInstall a named skill elsewhere Takes a marketplace skill name and writes it into a skills directory of your choice.
hf skills listList marketplace skills
hf skills updateUpdate installed skills Refreshes the marketplace skills installed in the project; add a name to update just one.
hf extensions install hf-claudeInstall a CLI extension Extensions are public GitHub repositories named hf-NAME, optionally prefixed with their owner.
hf extensions listList installed extensions
hf extensions searchSearch available extensions Looks on GitHub for repositories tagged with the hf-extension topic.
hf extensions updateUpdate all extensions Give an extension name to bring only that one to its latest version.
hf extensions remove claudeRemove an extension
Logging in and tokens 13
Older tutorials write these commands as huggingface-cli login, whoami and logout. That command has been removed; hf, introduced in v0.34, replaces it.
Command What it does
hf auth loginLog in to the Hub Starts a browser login by default: it prints a URL and a short code, then saves a self-refreshing token.
hf auth login --forceLog in again Without this flag an existing login skips the prompt; use it to switch tokens.
hf auth login --token $HF_TOKENLog in with a token Non-interactive form for scripts; the token comes from an environment variable, not from the command history.
hf auth login --token $HF_TOKEN --add-to-git-credentialLog in and add git credential Also saves the token in the configured git credential helper, which matters only when you run git yourself.
hf auth login --format agentLog in from an AI agent Never prompts: it runs the browser flow and prints instructions the agent passes on to its user.
hf auth whoamiShow the logged-in account Prints your username and the organizations you belong to, or an error when not logged in.
hf auth whoami --format jsonShow the account as JSON
hf auth logoutLog out Deletes all tokens stored on the machine; a login that comes from the HF_TOKEN variable is not affected.
hf auth logout --token-name my-tokenRemove one stored token
hf auth listList stored tokens Shows every access token saved on the machine; ls works as an alias.
hf auth switchSwitch between stored tokens Makes another saved access token the active one.
hf auth switch --token-name my-tokenSwitch to a named token
hf auth tokenPrint the current token Writes the active access token to stdout, so it can be piped into another command.
Downloading files and repositories 20
Command What it does
hf download REPO_IDDownload a repository With only a repo ID, every file of the model repo goes into the cache and the snapshot path is printed.
hf download gpt2 config.jsonDownload a single file The last line of output is always the local path of the file.
hf download gpt2 config.json model.safetensorsDownload several named files
hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensorsDownload a file from a subfolder Write the path inside the repo in POSIX form, with forward slashes.
hf download meta-llama/Llama-3.2-1B-Instruct --include "*.safetensors" --exclude "*.bin"Download files by pattern Glob patterns pick the files: --include keeps matches, --exclude drops them.
hf download HuggingFaceH4/ultrachat_200k --repo-type datasetDownload a dataset Without --repo-type the ID is read as a model repo.
hf download HuggingFaceH4/zephyr-chat --repo-type spaceDownload a Space
hf download bigcode/the-stack --repo-type dataset --revision v1.1Download a specific revision --revision takes a commit hash, branch name or tag; the default is the latest commit on main.
hf download hf://datasets/bigcode/[email protected] Download with an hf:// URI The URI already carries repo type and revision, so --repo-type and --revision raise an error next to it.
hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquetDownload one file from a pull request
hf download hf://datasets/HuggingFaceM4/FineVision/art/Download a subfolder The trailing slash marks the path as a folder.
hf download hf://openai-community/gpt2/config.jsonDownload with a bare model URI A URI with no type prefix points at a model repo.
hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyuDownload a file into a folder The file lands in that folder, not the cache; a .cache/huggingface subfolder there tracks what is up to date.
hf download meta-llama/Llama-3.2-1B-Instruct --local-dir ./models/llamaDownload a repo into a folder
hf download openai-community/gpt2 --dry-runPreview a download Lists every file with the bytes still to fetch and downloads nothing.
hf download adept/fuyu-8b --cache-dir ./path/to/cacheUse another cache directory Overrides the default cache location, which comes from HF_HOME.
hf download gpt2 config.json --token=hf_****Pass a token explicitly For private or gated repos when the token saved by the login should not be used.
hf download gpt2 --quietDownload quietly Only the final path is printed, which suits passing the result to another command in a script.
hf download REPO_ID --force-downloadDownload again despite the cache Fetches the files even when cached copies exist.
hf download REPO_ID --max-workers INTEGERSet parallel download workers Eight workers run in parallel unless another number is given.
Uploading files and folders 19
Command What it does
hf upload REPO_ID LOCAL_PATH PATH_IN_REPOUpload a file or folder LOCAL_PATH defaults to the current directory, and a repo that does not exist yet is created.
hf upload my-cool-model . .Upload the current directory Sends the working directory to the root of the repo.
hf upload my-cool-model ./models .Upload one folder
hf upload my-cool-model ./path/to/curated/data /data/trainUpload to a path in the repo The third argument is the destination folder inside the repository.
hf upload Wauplin/my-cool-model ./models/model.safetensorsUpload a single file With no third argument the file keeps its local name in the repo.
hf upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensorsUpload a file to a repo folder
hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"Mirror a local folder to a Space Uploads everything except the logs folder and deletes remote files that are gone locally.
hf upload Wauplin/my-cool-dataset ./data /train --repo-type=datasetUpload to a dataset
hf upload MyCoolOrganization/my-cool-model . .Upload to an organization The organization has to be written in the repo ID; otherwise the repo is a personal one.
hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104Upload to a branch or pull request Targets a revision other than main; a missing branch is created from main unless --create-pr is set.
hf upload bigcode/the-stack . . --repo-type dataset --create-prUpload as a new pull request For repos you cannot push to: the files go into a pull request for the owners to review.
hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csvUpload with an hf:// URI Repo type, revision and path in the repo are all read from the URI.
hf upload hf://Wauplin/my-cool-model ./modelsUpload a folder to a URI
hf upload training-model logs/ --every=10Upload at regular intervals Commits the folder again every 10 minutes, for example training logs.
hf upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%"Set the commit message Replaces the default commit title and description.
hf upload Wauplin/my-cool-model ./models . --token=hf_****Upload with an explicit token Otherwise the token saved by hf auth login is used.
hf upload Wauplin/my-cool-model ./models . --quietUpload quietly Prints only the URL of the uploaded files.
hf upload REPO_ID --privateCreate the repo as private Applies only when the upload creates the repo; an existing repo keeps its visibility.
hf upload HuggingFaceM4/Docmatix --repo-type=dataset /path/to/local/docmatixUpload a very large folder Files are streamed in several commits; rerunning the same command after an interruption skips what is already uploaded.
Working through git 4
Command What it does
git clone [email protected] :bigscience/bloomClone a model repository with git SSH form from the Hub docs; add your public key in the account settings to reach private repos or push.
git xet installSet up git-xet Run once before cloning, because repositories on the Hub are Xet-backed.
git lfs installSet up Git LFS
hf lfs-enable-largefiles PATHEnable large files in a clone Sets up git-lfs in the local repository at PATH to push large files in chunks through a multipart transfer agent.
Creating and managing repositories 22
Command What it does
hf repos create REPO_IDCreate a repository Makes a model repo unless --repo-type says dataset or space.
hf repos create my-cool-dataset --repo-type dataset --privateCreate a private dataset
hf repos create my-gradio-space --repo-type space --sdk gradioCreate a Gradio Space The reference marks --sdk as required whenever the type is space.
hf repos create my-jupyterlab --type space --template SpacesExamples/jupyterlabCreate a Space from a template Takes a template repo ID or its short name; hf spaces templates lists them.
hf repos create my-model --region usCreate a repo in a cloud region Accepts us or eu and needs a Team plan or above.
hf repos create REPO_ID --exist-okCreate only if missing Stops the command from failing when the repo is already there.
hf repos lsList your repositories Covers models, datasets, Spaces and buckets with storage use, largest first; only the first 30 are shown.
hf repos ls --type modelList one repository type --type also accepts dataset, space and bucket.
hf repos ls --search "bert"Search your repositories by name
hf repos ls --namespace my-orgList an organization's repositories
hf repos ls --limit 0List repositories without a limit
hf repos ls -qPrint repository IDs only
hf repos ls --limit 0 --format json | jq '.[].id'Export all repository IDs JSON output piped through jq; --limit 0 makes the export cover every repo.
hf repos duplicate openai/gdpval --type datasetDuplicate a repository Copies it on the server into your namespace and keeps the git history.
hf repos duplicate openai/gdpval myorg/my-gdpval --type dataset --privateDuplicate into an organization The second ID names the copy; --private hides it.
hf repos delete Wauplin/my-cool-modelDelete a repository Cannot be undone; -y answers the confirmation prompt in advance.
hf repos delete my-cool-dataset --repo-type datasetDelete a dataset repository
hf repos move old-namespace/my-model new-namespace/my-modelMove a repo to another namespace
hf repos settings Wauplin/my-cool-model --gated autoGate access to a repository --gated takes auto, manual or false.
hf repos settings my-model --privateMake a repository private
hf repos settings REPO_ID --publicMake a repository public
hf repos settings my-space --repo-type space --protectedProtect a Space The protected setting exists for Spaces only.
Finding models 20
Command What it does
hf models lsList trending models
hf models ls --search "lora"Search models
hf models ls --author QwenList models by author
hf models ls --pipeline-tag summarizationList models for a task
hf models ls --num-parameters min:6B,max:128BFilter models by parameter count
hf models ls --no-gated --author googleList only non-gated models --gated shows the opposite set, models that need an access request.
hf models ls --apps llama.cppList models an app can run
hf models ls --sort downloads --limit 10List the most downloaded models Sort keys are created_at, downloads, last_modified, likes and trending_score.
hf models ls --inference-provider fireworks-ai --sort downloadsList models served by a provider
hf models ls --warm --search llamaList models that are served now --warm keeps models that at least one inference provider is currently serving.
hf models ls meta-llama/Llama-3.2-1B-InstructList a model repo's files With a repo ID the command lists files; with none it lists models.
hf models ls meta-llama/Llama-3.2-1B-Instruct -RList model files recursively
hf models ls meta-llama/Llama-3.2-1B-Instruct --tree -hShow model files as a tree Tree layout with sizes in human-readable units.
hf models ls meta-llama/Llama-3.2-1B-Instruct --revision mainList files at a revision
hf models info Lightricks/LTX-2Show model details
hf models info Qwen/Qwen3.5-9B --expand downloads,likes,tagsShow selected model properties Returns only the listed properties plus the ID.
hf models card google/gemma-4-31B-itPrint a model card Prints the README: the YAML metadata followed by the text.
hf models card google/gemma-4-31B-it --metadataPrint model card metadata
hf models card google/gemma-4-31B-it --metadata --format jsonPrint card metadata as JSON
hf models card google/gemma-4-31B-it --textPrint model card text only The YAML frontmatter at the top is left out.
Finding datasets 16
Command What it does
hf datasets lsList trending datasets
hf datasets ls --search "code"Search datasets
hf datasets ls --filter benchmark:officialList official benchmark datasets These are the datasets that have a leaderboard.
hf datasets ls --sort downloads --limit 10List the most downloaded datasets
hf datasets ls HuggingFaceFW/finewebList a dataset repo's files
hf datasets ls HuggingFaceFW/fineweb -R -hList dataset files with sizes
hf datasets ls HuggingFaceFW/fineweb --treeShow dataset files as a tree
hf datasets info HuggingFaceFW/finewebShow dataset details
hf datasets card HuggingFaceFW/finewebPrint a dataset card
hf datasets card HuggingFaceFW/fineweb --metadata --format jsonPrint dataset metadata as JSON
hf datasets leaderboard SWE-bench/SWE-bench_VerifiedShow a benchmark leaderboard Lists model scores for the benchmark, 20 results unless --limit says otherwise.
hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5 --format jsonExport top leaderboard entries
hf datasets parquet cfahlgren1/hub-statsList parquet file URLs of a dataset Eligible datasets are converted to Parquet by the Dataset Viewer; the table shows subset, split and URL.
hf datasets parquet cfahlgren1/hub-stats --subset modelsList parquet URLs of one subset
hf datasets parquet cfahlgren1/hub-stats --split trainList parquet URLs of one split
hf datasets sql "SELECT COUNT(*) AS rows FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet')"Query dataset parquet with SQL Runs the query with DuckDB, which has to be installed as a Python package or as its own CLI.
Finding Spaces and papers 17
Command What it does
hf spaces lsList trending Spaces
hf spaces ls --search "3d"Search Spaces
hf spaces ls --sort likes --limit 10List the most liked Spaces
hf spaces ls victor/deepsiteList a Space repo's files
hf spaces info victor/deepsiteShow Space details
hf spaces card mteb/leaderboardPrint a Space card
hf spaces search "generate image"Search Spaces semantically Semantic search over Spaces; returns 10 running Spaces unless told otherwise.
hf spaces search "identify objects in pictures" --sdk gradio --limit 5Search Spaces of one SDK
hf spaces search "remove background from photo" --description --jsonSearch with descriptions as JSON --description adds the AI-generated summary of each Space.
hf papers lsList daily papers
hf papers ls --sort=trendingList trending papers
hf papers ls --date=todayList today's papers --date also takes an ISO date such as 2025-01-23.
hf papers ls --week=2025-W09List papers of a week
hf papers ls --submitter=akhaliqList papers by submitter
hf papers search "vision language"Search papers
hf papers info 2601.15621Show paper details Returns the structured metadata of the paper as JSON.
hf papers read 2601.15621Read a paper as Markdown
Collections 8
Command What it does
hf collections lsList collections
hf collections ls --owner nvidiaList collections of an owner
hf collections info username/my-collection-slugShow a collection
hf collections create "My Models"Create a collection
hf collections create "My Models" --description "A collection of my favorite models" --privateCreate a private collection The description is limited to 150 characters.
hf collections add-item username/my-collection moonshotai/kimi-k2 modelAdd an item to a collection The last argument is the item type: model, dataset, space, paper, collection or bucket.
hf collections update username/my-collection --title "New Title"Rename a collection
hf collections delete username/my-collectionDelete a collection
Running and debugging Spaces 23
Command What it does
hf spaces pause username/my-spacePause a Space Paused time is not billed; the container is torn down, so files on its ephemeral disk are lost.
hf spaces restart username/my-spaceRestart a Space Also the way to bring a paused Space back.
hf spaces restart username/my-space --factory-rebootRebuild a Space from scratch Rebuilds the image and ignores the build cache.
hf spaces wait username/my-spaceWait until a Space is up Blocks until building and starting are over; exit code 0 means RUNNING, anything else a failure such as BUILD_ERROR.
hf spaces wait username/my-space --timeout 5mWait with a time limit The limit is a number with s, m, h or d; plain numbers are seconds.
hf spaces restart username/my-space && hf spaces wait username/my-spaceRestart and wait in one line
hf spaces logs username/my-spacePrint the run logs of a Space
hf spaces logs username/my-space --buildPrint the build logs Use it for a Space stuck in BUILD_ERROR; the default is the run log.
hf spaces logs -f username/my-spaceFollow Space logs Keeps printing until the server closes the stream.
hf spaces logs -n 50 username/my-spaceShow the last 50 log lines
hf spaces hardwareList Space hardware options The table includes pricing for each flavor.
hf spaces settings username/my-space --hardware t4-mediumChange Space hardware
hf spaces settings username/my-space --sleep-time 3600Set the sleep timeout Idle seconds before the Space sleeps, -1 for never; only on upgraded hardware.
hf spaces zero-gpu quotaCheck the ZeroGPU quota Shows how much GPU time is left and when the quota resets.
hf spaces dev-mode my-user-name/deepsiteEnable Dev Mode
hf spaces dev-mode SPACE_ID --stopDisable Dev Mode
hf spaces ssh username/my-spaceOpen an SSH session in a Space Connects to the Dev Mode container, prompting to enable Dev Mode if it is off; your SSH public key must be registered.
hf spaces ssh username/my-space --dry-runPrint the SSH command for a Space
hf spaces ssh username/my-space --autoSSH and enable Dev Mode unasked
hf spaces ssh username/my-space -i ~/.ssh/id_ed25519SSH with a chosen identity file
hf spaces hot-reload username/repo-name app.pyEdit a Space file live Opens an interactive editor on the remote Python file and reloads it with no rebuild or restart.
hf spaces hot-reload username/repo-name -f app.pyHot-reload from a local file Patches the remote app.py with the local copy.
hf spaces templatesList Space templates A template from this list can be given to hf repos create with --template.
Space secrets, variables and volumes 12
Command What it does
hf spaces secrets ls username/my-spaceList Space secrets Shows keys, descriptions and update times; secret values are write-only and never printed.
hf spaces secrets add username/my-space -s OPENAI_API_KEY=sk-...Add or update a secret A key that already exists is overwritten.
hf spaces secrets add username/my-space -s HF_TOKENAdd a secret from your environment A name with no value is read from the local environment, which keeps it out of the shell history.
hf spaces secrets add username/my-space --secrets-file .env.secretsLoad secrets from a file
hf spaces secrets delete username/my-space OPENAI_API_KEY --yesDelete a secret
hf spaces variables ls username/my-spaceList Space variables Variables are not secret, so the list shows values as well as keys.
hf spaces variables add username/my-space -e MODEL_ID=gpt2 -e MAX_TOKENS=512Add environment variables
hf spaces variables add username/my-space --env-file .envLoad variables from a file
hf spaces variables delete username/my-space MAX_TOKENS --yesDelete a variable
hf spaces volumes set username/my-space -v hf://models/username/my-model:/modelsMount a volume in a Space Replaces the current set of volumes; data on a mounted volume or bucket survives restarts.
hf spaces volumes ls username/my-spaceList Space volumes
hf spaces volumes delete username/my-spaceRemove all Space volumes
Discussions and pull requests 18
Command What it does
hf discussions list username/my-modelList open discussions and PRs Only open items are listed unless --status says otherwise.
hf discussions list username/my-model --kind pull_request --status mergedList merged pull requests Kinds are discussion, pull_request or all; statuses are open, closed, merged, draft or all.
hf discussions list username/my-model --author aliceList discussions by author
hf discussions ls username/my-model --quietPrint discussion numbers only
hf discussions info username/my-model 5Show a discussion or PR Prints title, status and author plus every event of the conversation.
hf discussions diff username/my-model 5Show the diff of a pull request
hf discussions create username/my-model --title "Bug report"Open a discussion
hf discussions create username/my-model --title "Feature request" --body "Please add X"Open a discussion with a description
hf discussions create username/my-model --title "Report" --body-file report.mdOpen a discussion from a file
hf discussions create username/my-model --title "Fix typo" --pull-requestOpen a pull request The flag can be shortened to --pr.
hf discussions comment username/my-model 5 --body "Thanks for reporting!"Comment on a discussion
hf discussions comment username/my-model 5 --body-file review.mdComment from a file A dash as the file name reads the text from stdin.
hf discussions edit username/my-model 5 abc123 --body "Updated comment."Edit a comment The comment ID comes from hf discussions info.
hf discussions close username/my-model 5Close a discussion or PR Asks for confirmation unless --yes is given.
hf discussions close username/my-model 5 --yes --comment "Resolved"Close with a comment, no prompt
hf discussions reopen username/my-model 5 --yesReopen a discussion
hf discussions merge username/my-model 5 --yesMerge a pull request
hf discussions rename username/my-model 5 "Updated title"Rename a discussion
Buckets 22
Command What it does
hf buckets create my-bucketCreate a bucket Created under your own namespace; buckets are mutable object storage with no git history.
hf buckets create my-bucket --privateCreate a private bucket
hf buckets listList your buckets hf buckets ls is the shorthand for the same listing.
hf buckets ls my-orgList an organization's buckets
hf buckets list --search "checkpoint"Filter buckets by name
hf buckets info username/my-bucketShow bucket details The details come back as JSON.
hf buckets settings username/my-bucket --privateMake a bucket private
hf buckets settings username/my-bucket --publicMake a bucket public
hf buckets move user/old-bucket user/new-bucketRename or move a bucket
hf buckets delete username/my-bucket --yesDelete a bucket Without --yes the command asks for confirmation first.
hf buckets list username/my-bucketList files in a bucket
hf buckets list username/my-bucket -R -hList bucket files recursively -h prints file sizes in readable units and shortens dates.
hf buckets list username/my-bucket --tree -h -RShow a bucket as a tree
hf buckets list username/my-bucket/sub -RList files under a prefix
hf buckets rm username/my-bucket/old-model.binRemove a file from a bucket
hf buckets rm username/my-bucket/logs/ --recursiveRemove everything under a prefix
hf buckets rm username/my-bucket --recursive --include "*.tmp"Remove bucket files by pattern --include and --exclude work only together with --recursive.
hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-runPreview a bucket removal
hf cp ./data.csv hf://buckets/username/my-bucket/logs/Copy a local file into a bucket A destination ending in a slash keeps the local file name.
hf cp hf://buckets/username/my-bucket/config.jsonCopy a bucket file to this folder With the destination left out, the file is written to the current directory.
hf cp hf://datasets/username/my-dataset/data/train/ hf://buckets/username/my-bucket/datasets/train/Copy a repo folder to a bucket The reverse direction, bucket to repo, is not supported yet.
hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/archive-bucket/logs/Copy between buckets A trailing slash on the source copies only the folder contents, rsync-style.
Syncing folders with a bucket 10
Command What it does
hf buckets sync ./data hf://buckets/username/my-bucketSync a folder up to a bucket Compares both sides and transfers only the files that changed.
hf buckets sync hf://buckets/username/my-bucket ./dataSync a bucket down to a folder
hf buckets sync ./data hf://buckets/username/my-bucket --deleteSync and delete extra files Removes files at the destination that the source no longer has.
hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"Sync only matching files
hf buckets sync ./data hf://buckets/username/my-bucket --existingSync without creating new files Updates files already at the destination and adds nothing new.
hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existingSync only new files Creates missing files and leaves those already at the destination untouched.
hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonlSave a sync plan Writes the planned operations to a JSONL file for review and transfers nothing.
hf buckets sync --apply sync-plan.jsonlApply a saved sync plan
hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq .Print the sync plan as JSONL
hf sync SOURCE DESTSync with the short alias Top-level alias of hf buckets sync with the same options.
Cache management 21
hf cache scan and hf cache delete were removed in v1.0. hf cache ls, hf cache rm and hf cache prune are the replacements.
Command What it does
hf cache lsList cached repositories One line per repository with its size on disk; the summary gives totals for repos and revisions.
hf cache ls --revisionsList cached revisions Breaks each repository down into its snapshots.
hf cache ls --filter "size>30g" --revisionsFind large cached revisions
hf cache ls --filter "size>1GB" --limit 20List large cache entries Filters also accept forms such as type=model and accessed>7d, and can be repeated.
hf cache ls --format jsonList the cache as JSON
hf cache list --sort size:descSort the cache listing Keys are accessed, modified, name and size, each with :asc or :desc; ls is the alias of list.
hf cache rm model/gpt2Delete a cached repository Shows what will go and asks for confirmation; the target is the repo ID with its type in front.
hf cache rm model/gpt2 --dry-runPreview a cache deletion
hf cache rm model/gpt2 --yesDelete from the cache without asking
hf cache rm hf://models/openai-community/gpt2Delete a cached repo by URI
hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-runDelete one cached file The file is removed from every cached revision; folders and glob patterns are not accepted.
hf cache rm model/t5-small 8f3ad1c --dry-runDelete a repo and a revision together Repositories and revision hashes can be mixed in one call.
hf cache rm $(hf cache ls --filter "accessed>1y" -q) -yDelete entries unused for a year The inner listing prints only IDs, which become the deletion targets.
hf cache pruneRemove unreferenced revisions Also clears .incomplete files from interrupted downloads and shared blobs that nothing references.
hf cache prune --dry-runPreview a cache prune
hf cache verify gpt2Verify cached file checksums Compares local files with the checksums on the Hub and exits non-zero on a mismatch.
hf cache verify deepseek-ai/DeepSeek-OCR --revision refs/pr/5Verify a specific revision
hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type datasetVerify a cached dataset
hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repoVerify a folder outside the cache
hf cache verify deepseek-ai/DeepSeek-OCR --fail-on-missing-files --fail-on-extra-filesFail on missing or extra files By default such files only produce warnings.
hf cache verify me/private-model --token hf_***Verify a private repo
Running Jobs 23
Command What it does
hf jobs run --name hello-world python:3.12 python -c 'print("Hello from the cloud!")'Run a command in a Docker image Starts the Job on Hugging Face infrastructure and shows its logs until it ends.
hf jobs run --detach python:3.12 python script.pyRun a Job in the background Returns at once and prints only the Job ID.
hf jobs run --flavor cpu-basic python:3.12 -- python --helpSeparate Job options from the command Everything after the double dash belongs to your command; Jobs leaves it uninterpreted.
hf jobs run --namespace my-org-name python:3.12 python -c 'print("Running in an org account")'Run under an organization
hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c 'select "hello world"'Run a Job from a Space The image argument here is a Space, not a Docker Hub image.
hf jobs run --timeout 2h pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel python train.pySet a Job timeout Jobs stop after 30 minutes by default; the value takes an s, m, h or d suffix.
hf jobs run -e FOO=foo python:3.12 python script.pyPass an environment variable Repeat -e for more variables, or load a whole file with --env-file.
hf jobs run --secrets HF_TOKEN python:3.12 python script.pyPass your Hub token as a secret A secret named without a value is read from your environment; secrets are encrypted on the server.
hf jobs run -v hf://org/my-model:/data -v hf://buckets/org/b:/mnt python:3.12 python script.pyMount repos and buckets as volumes Models, datasets and Spaces mount read-only; buckets are read-write unless :ro is appended.
hf jobs run --attempts 3 --detach python:3.12 python train.pyRetry a failing Job The count includes the first run, so 3 allows up to two retries.
hf jobs run --detach --expose-public 8000 python:3.12 python -m http.server 8000Expose a port without a token Plain --expose keeps the port behind token authentication; both flags can be repeated.
hf jobs run --ssh --detach python:3.12 sleep infinityStart a Job reachable over SSH Access is limited to users with write access to the namespace who have an SSH key registered.
hf jobs run -l my-label --label foo=bar ubuntu echo "This Job has multiple labels"Label a Job Labels are key=value metadata; a key given alone gets an empty value.
hf jobs run --name training-v2 python:3.12 python train.pyName a Job Names need not be unique; without one a name is derived from the image or script.
hf jobs run python:3.12 python train.py && echo "training succeeded"Chain a command after a Job A non-detached run exits non-zero when the Job fails, so the second command is skipped.
hf jobs uv run my_script.pyRun a UV script UV scripts are Python files that declare their dependencies inline; the guide marks the feature experimental.
hf jobs uv run --flavor t4-small ml_training.pyRun a UV script on a GPU
hf jobs uv run --with transformers --with torch train.pyAdd packages to a UV run
hf jobs uv run process.py input.csv output.parquetPass arguments to a UV script
hf jobs uv run https://huggingface.co/datasets/username/scripts/resolve/main/example.pyRun a UV script from a URL
hf jobs uv run -v ./my-data:/data process.pyMount a local folder in a Job The folder is first synced to your jobs-artifacts bucket and mounted read-only unless :rw is added.
hf jobs uv run --dry-run script.pyPreview a UV Job Shows the configuration that would be sent and submits nothing.
hf jobs hardwareList Job hardware flavors
Monitoring Jobs 21
Command What it does
hf jobs lsList running Jobs Shows running and scheduling Jobs only, 100 at most.
hf jobs ls -aList all Jobs Lifts the default restriction to running and scheduling Jobs.
hf jobs ls --status running,schedulingFilter Jobs by status
hf jobs ls -a --label model=Qwen3-06BFilter Jobs by label
hf jobs ls -a --name training-v2Filter Jobs by name --name is shorthand for --label name=NAME.
hf jobs ps -a --limit 0List every Job without a cap ps is another spelling of ls; --limit 0 removes the cap of 100.
hf jobs inspect JOB_IDShow Job details Takes one Job ID or several at once.
hf jobs logs JOB_IDPrint Job logs Prints what is available so far and returns.
hf jobs logs -f JOB_IDFollow Job logs Keeps streaming until the Job completes.
hf jobs logs --tail 20 JOB_IDShow the last log lines Combined with -f, streaming starts from those last lines.
hf jobs statsShow resource usage of running Jobs
hf jobs stats JOB_IDShow resource usage of one Job
hf jobs cancel JOB_IDCancel a Job
hf jobs wait JOB_IDWait for a Job to finish Blocks until the Job reaches a terminal state and exits non-zero if it failed.
hf jobs ls -q | xargs hf jobs waitWait for all running Jobs
hf jobs rerun JOB_IDRun a Job again Starts a new Job from the saved spec, attempt count included, and streams its logs.
hf jobs labels JOB_ID --name training-v2Rename a Job Passing --name alone keeps the other labels, whereas --label replaces them all.
hf jobs expose JOB_ID 8000 --public 9000Change exposed ports Applies without rerunning the Job; ports left out of the new list are closed.
hf jobs expose JOB_ID --clearClose all exposed ports
hf jobs ssh JOB_IDSSH into a running Job Works for Jobs that were started with the --ssh flag.
hf jobs ssh JOB_ID --dry-runPrint the SSH command for a Job
Scheduled Jobs 13
Command What it does
hf jobs scheduled run @hourly --name hourly-task python:3.12 python -c 'print("This runs every hour!")'Schedule a recurring Job The schedule is @hourly, @daily, @weekly, @monthly, @yearly, @annually or a CRON expression.
hf jobs scheduled run "*/5 * * * *" python:3.12 python -c 'print("This runs every 5 minutes!")'Schedule with a CRON expression
hf jobs scheduled uv run @hourly --name hourly-script my_script.pySchedule a UV script
hf jobs scheduled run @daily --timeout 4h python:3.12 python daily_task.pySchedule a Job with a timeout
hf jobs scheduled lsList active scheduled Jobs
hf jobs scheduled ls --allList all scheduled Jobs
hf jobs scheduled ls --status suspendedList suspended scheduled Jobs
hf jobs scheduled inspect SCHEDULED_JOB_IDShow a scheduled Job
hf jobs scheduled suspend SCHEDULED_JOB_IDPause a scheduled Job
hf jobs scheduled resume SCHEDULED_JOB_IDResume a scheduled Job
hf jobs scheduled reschedule SCHEDULED_JOB_ID "0 9 * * 1"Change the schedule Affects future runs; the example expression means Mondays at 9:00.
hf jobs scheduled trigger SCHEDULED_JOB_IDRun a scheduled Job now Starts one run immediately and leaves the schedule as it is.
hf jobs scheduled delete SCHEDULED_JOB_IDDelete a scheduled Job
Inference Endpoints 16
hf inference-endpoints is the legacy alias of hf endpoints and still works.
Command What it does
hf endpoints lsList Inference Endpoints Lists your own namespace; --namespace targets an organization.
hf endpoints hardwareList deployable hardware Each row is a valid vendor, region, accelerator and instance combination with its hourly price and your quota.
hf endpoints hardware --vendor aws --region eu-west-1Filter hardware by cloud and region The filter flags are the ones deploy takes, so the values can be reused as they are.
hf endpoints catalog lsList catalog models One row per recipe, which is a tested hardware and engine combination.
hf endpoints catalog ls --engine vllm --task text-generation --search llama --limit 10Filter the catalog
hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-InstructDeploy a catalog model Uses the default recipe of that model.
hf endpoints catalog deploy --recipe artisanal-quinoa-yz9ynamxDeploy a specific recipe Recipe IDs come from the catalog listing; --repo cannot be combined with --recipe.
hf endpoints catalog deploy --repo openai/gpt-oss-120b --name my-endpointDeploy a catalog model under a name
hf endpoints deploy my-endpoint --repo gpt2 --framework pytorch --accelerator cpu --instance-size x2 --instance-type intel-iclDeploy an endpoint from a Hub repo The reference also marks --vendor and --region as required; hf endpoints hardware lists valid values.
hf endpoints describe my-endpointShow endpoint status and metadata
hf endpoints update my-endpoint --min-replica 2Change the minimum replica count
hf endpoints update gpt-oss-120b-vllm --tensor-parallel-size 4 --data-parallel-size 2Retune a running endpoint Pass the sizes on their own; the current engine image is fetched and updated in place.
hf endpoints pause my-endpointPause an endpoint
hf endpoints resume my-endpointResume an endpoint
hf endpoints scale-to-zero my-endpointScale an endpoint to zero
hf endpoints delete my-endpoint --yesDelete an endpoint Deletion is permanent; --yes skips the confirmation.
Webhooks 9
Command What it does
hf webhooks lsList your webhooks
hf webhooks info wh-abc123Show webhook details Full details are printed as JSON.
hf webhooks create --url https://example.com/hook --watch model:bert-base-uncasedCreate a webhook for a URL --watch takes type:name with type model, dataset, space, bucket, org or user, and can be repeated.
hf webhooks create --url https://example.com/hook --watch org:HuggingFace --watch model:gpt2 --domain repoWatch several items, repo events only --domain limits events to repo or discussions; without it both are sent.
hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-cCreate a webhook that runs a Job Triggers the Job in place of pinging a URL; --url and --job-id exclude each other.
hf webhooks update wh-abc123 --url https://new-url.com/hookChange a webhook Only the options given are changed, but --watch replaces the whole watched list.
hf webhooks disable wh-abc123Disable a webhook
hf webhooks enable wh-abc123Enable a webhook
hf webhooks delete wh-abc123 --yesDelete a webhook
Environment variables 22
Command What it does
HF_TOKENAuthenticate with a token When set, it wins over any token saved by a login.
HF_HOMEMove the Hugging Face data folder Holds the token and the cache; defaults to ~/.cache/huggingface unless XDG_CACHE_HOME is set.
HF_HUB_CACHEMove the repository cache Where downloaded models, datasets and Spaces are kept; defaults to $HF_HOME/hub.
HF_XET_CACHEMove the Xet cache Xet keeps its shard cache and its staging data for uploads here, $HF_HOME/xet by default.
HF_TOKEN_PATHChange where the token is stored The default location is the file $HF_HOME/token.
HF_HUB_OFFLINE=1Work offline from the cache No HTTP calls reach the Hub: downloads resolve to cached files and fail when nothing is cached.
export HF_HUB_DOWNLOAD_TIMEOUT=30Raise the download timeout Cure for read timeouts on slow connections; the default wait is 10 seconds.
HF_HUB_ETAG_TIMEOUTSet the metadata request timeout Seconds to wait for repo metadata before falling back to cached files, 10 by default.
HF_HUB_VERBOSITYSet the log level Accepts the five standard levels from debug to critical; warning is the default.
HF_DEBUGTurn on debug logging Besides DEBUG-level logs, every request is printed as an equivalent cURL command.
HF_HUB_DISABLE_PROGRESS_BARS=1Hide progress bars
HF_HUB_DISABLE_TELEMETRY=1Turn off telemetry Stops usage data collection across the Hugging Face libraries; DO_NOT_TRACK has the same effect.
HF_HUB_DISABLE_UPDATE_CHECK=1Silence the update notice Skips the PyPI check hf makes at startup, at most once a day, and the hint about the hf-cli skill.
HF_HUB_DISABLE_IMPLICIT_TOKEN=1Send the token only for writes By default a logged-in user sends the token with every request, which also covers private and gated repos.
HF_HUB_DISABLE_SYMLINKS=1Keep symlinks out of the cache Files are copied into the snapshot folders, at the cost of duplicates; one use is a cache shared across operating systems.
HF_HUB_DISABLE_XETTurn off hf-xet transfers hf-xet is otherwise used automatically whenever it is installed.
HF_XET_HIGH_PERFORMANCE=1 hf download ...Download with maximum throughput Raises concurrency and buffer sizes; the Hub docs advise it for high-bandwidth machines with at least 64 GB of RAM.
HF_HUB_ENABLE_HF_TRANSFEROld fast-transfer switch Deprecated: hf_transfer can no longer be used now that all transfers go through hf-xet.
NO_COLORTurn off coloured output When set, the hf CLI prints no ANSI colour codes.
XDG_CACHE_HOMEFallback for the data folder Read only while HF_HOME is unset; the data folder then becomes $XDG_CACHE_HOME/huggingface.
HUGGING_FACE_HUB_TOKENDeprecated token variable Still works but no longer takes precedence over HF_TOKEN, which replaces it.
HUGGINGFACE_HUB_CACHEDeprecated cache variable Still works but HF_HUB_CACHE, its replacement, wins when both are set.
No row on this page matches that filter.
Notes
Authentication hf auth login opens a browser login and saves a token on the machine; private and gated repositories need one, as do uploads. hf auth whoami confirms which account is active and hf auth logout removes the stored tokens. On a shared machine or in CI, the token can instead be passed per command with --token or set in HF_TOKEN , which is used in place of the stored token. hf env prints the versions and paths the library sees, which is what to paste into a bug report.
Downloading and uploading hf download REPO_ID fetches a repository into the cache and prints the local path; hf download meta-llama/Llama-3.2-1B-Instruct --include "*.safetensors" --exclude "*.bin" restricts it to patterns, which saves time and space for a repo that ships its weights in several formats. hf upload REPO_ID LOCAL_PATH PATH_IN_REPO pushes a file or folder and creates the repo when it does not exist yet; hf repos create REPO_ID makes one explicitly. The git route is git clone [email protected] :bigscience/bloom after git xet install, and hf lfs-enable-largefiles PATH prepares a clone for files over 5 GB.
The cache Everything downloads into ~/.cache/huggingface/hub (or under HF_HOME ), and models of tens of gigabytes accumulate there. hf cache ls reports what is cached with sizes per repository, and hf cache ls --revisions breaks that down per revision. hf cache rm model/gpt2 deletes a repository after a confirmation prompt and hf cache prune clears revisions that no branch or tag points to — the pair to run when a workstation runs out of space. The interactive selector of the old delete-cache command no longer exists. hf version prints the CLI version.
Questions
Is huggingface-cli still available? No. The huggingface_hub migration guide says the deprecated huggingface-cli has been removed and that hf, introduced in v0.34, replaces it. The commands are grouped by resource, so the old login, whoami and logout became hf auth login, hf auth whoami and hf auth logout.
What replaced scan-cache and delete-cache? hf cache ls lists what is cached, hf cache rm model/gpt2 deletes a repository, a revision or a single file, and hf cache prune removes revisions that nothing references. The intermediate hf cache scan and hf cache delete commands were removed in v1.0 as well.
Where does hf download put the files? In the cache, by default ~/.cache/huggingface/hub, and it prints the resulting path on the last line. hf download meta-llama/Llama-3.2-1B-Instruct --local-dir ./models/llama writes to a folder of your choice instead, and the HF_HOME or HF_HUB_CACHE variables move the cache itself.
How do I log in on a server or in CI without a prompt? Set the HF_TOKEN environment variable, which is used in place of any stored token, or run hf auth login --token $HF_TOKEN. The guide recommends an environment variable so the token does not end up in the command history.
Is there still a separate command for uploading very large folders? The 2.1.1 reference lists none. The upload guide names hf upload REPO_ID LOCAL_PATH PATH_IN_REPO as the way to send very large folders too: files are streamed in several commits, and running the same command again after an interruption skips what was already uploaded.
Does HF_HUB_ENABLE_HF_TRANSFER still speed up transfers? No. The variable is deprecated because all transfers now go through hf-xet and hf_transfer cannot be used any more. The documented replacement for maximum throughput is HF_XET_HIGH_PERFORMANCE=1.
Sources and checks
Hugging Face Hub docs: Command Line Interface (CLI) guide, huggingface_hub 2.1.1 Installation, login, download, upload, repos, buckets, cache, Spaces, Jobs, webhooks and endpoints examples Hugging Face Hub docs: CLI reference generated from the hf implementation, huggingface_hub 2.1.1 Usage lines, options and examples of every hf command Hugging Face Hub docs: Environment variables reference, huggingface_hub 2.1.1 Environment variables read by huggingface_hub and the hf CLI Hugging Face Hub docs: Migrating to huggingface_hub v1.0 Removal of huggingface-cli and of the old cache commands Hugging Face Hub docs: Upload files to the Hub guide, huggingface_hub 2.1.1 Uploading very large folders with hf upload Hugging Face Hub documentation: Downloading models Cloning a repository with git, faster downloads
Every row on this page was matched to a line in the documentation above on 6 October 2026 . A binding that could not be found there is not listed.
Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.