Hugging Face

Published 2026-10-01Updated 2026-10-06

hf CLI

hf is the official Hugging Face command-line tool, provided by huggingface_hub. It interacts with the Hugging Face Hub for logging in, managing repositories, and downloading models and datasets. This article covers installation, updates, hf download usage, and the difference between the default cache directory and --local-dir local directory mode.

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
Bash
curl -LsSf https://hf.co/cli/install.sh | bash
  • Windows
Bash
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:

Bash
# 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:

Bash
hf --help

Update

Update to the latest version. This command automatically detects how hf was installed and updates it accordingly.

Bash
hf update

hf download

Command format:

Bash
hf download [OPTIONS] REPO_ID [FILENAMES]...
 
# You can also check the help
hf download --help

If 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:

Plain text
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.

Bash
hf download tencent/Hy-MT2-7B --local-dir ~/MyFiles/models/tencent/Hy-MT2-7B

Downloading Files to a Specific Directory

  • Download a single file to a directory:
Bash
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:
Bash
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:
Bash
hf download tencent/Hy-MT2-7B --local-dir ~/<local-path>/tencent/Hy-MT2-7B