The Hugging Face CLI: Download, Manage, and Run Any Model from the Terminal

If Ollama is how you run a model, Hugging Face is where nearly every open model actually lives. Ollama's own library is a curated shelf. Hugging Face is the warehouse behind it, with hundreds of thousands of models and datasets, including the exact quantization you want and the fine-tunes that never make it onto the shelf.

The hf command line tool is how you reach that warehouse without leaving the terminal. This guide covers installing it, signing in, downloading and uploading, managing the local cache before it eats your disk, and the part that ties it all together: running a Hugging Face model directly in Ollama, or with MLX on Apple Silicon.

One note before starting: the tool used to be called huggingface-cli. It is now just hf. Older guides use the long name, but the commands map over cleanly.

What the hf CLI Is, and How It Differs from Ollama

It helps to be clear about the split. Ollama is a runtime. It downloads a curated model, loads it, and serves it. The hf CLI is a client for the Hugging Face Hub. It fetches, manages, and uploads the raw model and dataset files themselves.

You reach for hf when the model you want is not in Ollama's library, when you need a specific quantization, when you want the dataset rather than the model, or when you want to publish something of your own. In practice the two tools work together: hf gets the files, Ollama or MLX runs them.

Installing the CLI

There are a few ways in, and the right one depends on your machine.

Homebrew (cleanest on macOS). This installs the tool on its own, isolated from your Python:

brew install hf

Standalone installer (macOS and Linux):

curl -LsSf https://hf.co/cli/install.sh | bash

With pip, and the --break-system-packages reality. If you install through the Python that Homebrew manages, pip will refuse with an "externally-managed-environment" error. This is PEP 668 at work: Homebrew marks its Python as managed so that pip does not fight with Brew over the same files. The direct way around it is the flag you have probably already used:

python3 -m pip install -U "huggingface_hub[cli]" --break-system-packages

That works, and for a personal machine it is usually fine. The cost is that the package goes into Homebrew's Python, where a future brew upgrade can touch the same directory. The cleaner habit, when you want isolation, is a virtual environment:

python3 -m venv ~/.venvs/hf
source ~/.venvs/hf/bin/activate
pip install -U "huggingface_hub[cli]"

Or use uv, which sidesteps the whole issue and runs the latest version without a permanent install:

uvx hf <command>

For the CLI specifically, brew install hf avoids the Python question entirely. Keep --break-system-packages for the cases where you genuinely want a package in your system Python, such as mlx-lm later in this guide.

Confirm the install:

hf version

Signing In

Public models download without an account. But gated models (like some Llama releases), private repos, and uploads all need authentication. Create a token at huggingface.co under Settings, Access Tokens, then:

hf auth login              # interactive, paste your token
hf auth login --token $HF_TOKEN   # non-interactive, for scripts
hf auth whoami             # check who you are logged in as
hf auth logout

A read token is enough for downloading gated models. Use a write token only when you plan to upload.

Downloading Models and Datasets

hf download is the workhorse. It pulls into a local cache and prints the path.

# an entire model repository
hf download meta-llama/Llama-3.2-3B-Instruct

# a single file only
hf download openai-community/gpt2 config.json

# just the weights, skipping the large duplicates
hf download stabilityai/stable-diffusion-xl-base-1.0 \
  --include "*.safetensors" --exclude "*.fp16.*"

# a dataset instead of a model
hf download HuggingFaceH4/ultrachat_200k --repo-type dataset

# preview what would download, without pulling anything
hf download meta-llama/Llama-3.2-3B-Instruct --dry-run

The --include and --exclude patterns matter more than they look. A model repo often holds several quantizations and formats. Downloading blindly can pull tens of gigabytes you do not need. Preview with --dry-run first when a repo is large.

Running a Hugging Face Model Directly in Ollama

This is the bridge worth knowing, and it surprises people who assume Ollama can only run its own library. Ollama can run any GGUF model on the Hub directly, no manual download or import:

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF

You can write hf.co or huggingface.co. By default Ollama picks the Q4_K_M quantization if the repo has it. To choose a different one, add it after a colon:

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:IQ3_M

Quantization names are case-insensitive, and you can pass the full GGUF filename instead if you want an exact file. This one line is the reason the Hub matters even when you live in Ollama: the moment a model you want is not on Ollama's shelf, it is almost certainly a hf.co/... away.

Apple Silicon: Running with MLX

On a Mac with Apple Silicon there is a second runtime worth knowing, and it is often faster than a GGUF path because it uses Apple's own framework. MLX runs models natively on the Mac's unified memory. The mlx-lm package is the tool, and this is a case where the --break-system-packages install is the natural fit:

python3 -m pip install mlx-lm --break-system-packages

The MLX community publishes pre-converted models on the Hub under the mlx-community organization. You point mlx-lm straight at a Hub repo and it downloads through the same Hugging Face cache:

# one-shot generation
mlx_lm.generate --model mlx-community/Qwen2.5-7B-Instruct-4bit \
  --prompt "Explain quantization in two sentences."

# interactive chat
mlx_lm.chat --model mlx-community/Qwen2.5-7B-Instruct-4bit

# a local OpenAI-compatible server
mlx_lm.server --model mlx-community/Qwen2.5-7B-Instruct-4bit

The practical takeaway for Mac users: try the same model both ways. Ollama with a GGUF is simpler and more universal. MLX with an mlx-community build is often faster on Apple Silicon. Both pull from Hugging Face, so the CLI skills here serve both.

Managing the Local Cache

Downloaded models pile up fast, and they are large. The cache is the first place to look when a disk fills.

hf cache ls              # what is cached and how big
hf cache ls --revisions  # include every stored revision
hf cache rm model/gpt2   # remove a specific model
hf cache prune           # drop revisions nothing references
hf cache verify gpt2     # check file integrity

hf cache prune is the safe cleanup: it only removes old revisions that nothing points to anymore, reclaiming space without breaking anything you still use. Run it every so often on a machine you download to often.

The cache lives under ~/.cache/huggingface by default. To put it on a bigger or faster disk, set HF_HOME to a new path in your shell profile.

Uploading Your Own Models

When you fine-tune or convert a model, hf publishes it. This needs a write token.

# create a repo (add --private or --repo-type dataset as needed)
hf repos create my-username/my-cool-model

# upload a folder
hf upload my-username/my-cool-model ./output .

# open a pull request instead of pushing directly
hf upload my-username/my-cool-model ./output . --create-pr

For a shared or organization repo, --create-pr is the courteous default. It puts your change up for review rather than committing straight to main.

How This Fits Together

Three tools, three jobs. The hf CLI gets and manages the files. Ollama runs them simply and everywhere. MLX runs them fast on a Mac. Once you can pull any model from the Hub, choose its quantization, and hand it to the right runtime, the entire open-model ecosystem is open to you from the terminal, not just the curated slice.

A good next step: pick a model that is not in Ollama's library, find its GGUF repo on Hugging Face, and run it with a single ollama run hf.co/... line. That is the moment the Hub stops being a website and becomes part of your toolkit.

References

• Hugging Face CLI Documentation↗
• Run any GGUF model from Hugging Face in Ollama↗
• MLX and mlx-lm↗
• Hugging Face Models Hub↗