Introduction
hf is a built-in CLI tool provided by the huggingface_hub Python library.
It lets you interact with the Hugging Face Hub directly from the command line, including but not limited to: logging in, creating repositories, and downloading files.
Installation
The official recommendation is a one-line install command, though you can also install it with uv, pip, homebrew, and similar tools.
- macOS and Linux
curl -LsSf https://hf.co/cli/install.sh | bash- Windows
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"The installer also installs a global hf-cli skill, available to any agent that reads the ~/.agents/skills directory.
If you don't need it, pass the --exclude-skill flag to skip installing it:
# macOS and Linux
curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill
# Windows
powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://hf.co/cli/install.ps1))) -ExcludeSkill"After installation completes, verify it with the following command:
hf --helpUpdate
Update to the latest version. This command automatically detects how hf was installed and updates it accordingly.
hf updatehf download
Command format:
hf download [OPTIONS] REPO_ID [FILENAMES]...
# You can also check the help
hf download --helpIf you don't pass --local-dir, files are downloaded to the Hugging Face cache directory by default β ~/.cache/huggingface/hub, configured via the HF_HOME environment variable.
This directory structure is designed for sharing multiple versions and deduplication, not for humans to read:
models--Qwen--Qwen3.8-27B/
βββ blobs/ # Actual file contents, named by hash
βββ refs/ # Branch name β commit hash mapping (e.g. main)
βββ snapshots/
βββ <commit_hash>/
βββ config.json β symlink pointing to ../../blobs/<hash>With --local-dir (local directory mode), files are placed directly under the specified path following the original directory structure of the repository. They are real files rather than symlinks, so you can move, copy, and archive them directly, which also makes offline deployment easier.
One thing to watch out for: --local-dir is the final destination directory for the files, and hf does not create an org/name subdirectory automatically. If you specify ~/MyFiles/models, all of the model's files are placed flat in that directory, so downloading several models will mix them together.
The best approach is to keep the local path consistent with the repository ID, that is, <root>/<org>/<name>, for example ~/MyFiles/models/JonathanColetti/Qwen3.8-27B-Uncensored-GGUF.
hf download tencent/Hy-MT2-7B --local-dir ~/MyFiles/models/tencent/Hy-MT2-7BDownloading Files to a Specific Directory
- Download a single file to a directory:
hf download JonathanColetti/Qwen3.8-27B-Uncensored-GGUF Qwen3.8-27B-Uncensored-Q5_K_M.gguf --local-dir ~/<local-path>/Qwen/qwen3.8- Download multiple files to a directory:
hf download JonathanColetti/Qwen3.8-27B-Uncensored-GGUF \
Qwen3.8-27B-Uncensored-Q5_K_M.gguf \
mmproj-Qwen3.8-27B-Uncensored-F16.gguf \
--local-dir ~/<local-path>/Qwen/qwen3.8- Download an entire repository to a directory:
hf download tencent/Hy-MT2-7B --local-dir ~/<local-path>/tencent/Hy-MT2-7B