If you’ve spun up a new GPU pod on RunPod, tried to authenticate with Hugging Face, and immediately hit this brick wall:

root@d9ad279414c6:/# hf auth login
bash: hf: command not found

Don’t worry, your pod isn’t broken. You just ran into a combination of missing packages and a slight shift in how Hugging Face handles its command-line tools.

Let’s get this sorted out in a few minutes so you can get back to loading your models.

---

Why Is This Happening?

Two simple reasons:

1. The package isn’t pre-installed: Many default PyTorch or CUDA Docker templates on RunPod ship with bare-bones Python environments. They come with PyTorch ready to go, but extra ecosystem packages like huggingface_hub aren’t baked into the image.
2. The command name changed: If you’ve been using Hugging Face for a while, you might remember huggingface-cli login. Hugging Face overhauled their CLI tool, changing the executable name to just hf. Furthermore, the login syntax now lives under hf auth login.

So if you are trying the modern hf command on a fresh container, Linux has no idea what tool you’re calling until we install it.

---

Step 1: Install or Update the Hugging Face Hub Package

To get access to the hf binary, you need to install the latest huggingface_hub package via pip.

Run this inside your RunPod terminal:

pip install -U huggingface_hub

If you want to be extra sure you get all extra features (like fast transfer tools), you can run:

pip install -U "huggingface_hub[cli]"

Once pip finishes building and placing the binaries, test it by asking for the help menu:

hf --help

If you see a list of available subcommands starting with auth, download, and upload, you are good to go!

---

Step 2: Log In to Hugging Face

Now that the system recognizes the command, run the login step:

hf auth login

The terminal will prompt you to enter your User Access Token.

1. Open your browser and go to huggingface.co/settings/tokens.
2. Generate a token (a Read token is fine if you only need to download gated models like Llama or Mistral; get a Write token if you plan on pushing weights).
3. Copy the token string, paste it into your RunPod terminal, and hit Enter.

---

Safe vs. Fast: Avoiding This on Pod Restarts

RunPod instances are ephemeral by nature. If you terminate your pod or reset the container, any package you installed in the root filesystem via pip install might disappear unless you saved it to your /workspace volume.

Here are two ways to handle this so you don’t keep typing commands every time you launch a pod:

The Quick Fix (Environment Variable)

Instead of running interactive logins inside the terminal every time, you can pass your token directly as an environment variable.

Before running your Python script or model downloader, run:

export HF_TOKEN="hf_your_actual_token_here"

Hugging Face libraries (transformers, diffusers, huggingface_hub) will automatically detect HF_TOKEN in your environment and authenticate without needing hf auth login at all.

Pro-tip: You can set HF_TOKEN inside the Environment Variables field when setting up your pod template in the RunPod web console. That way, every new instance boots up already logged in!

---

Quick Recap

• The Problem: The CLI package isn’t installed in the container image, so hf isn’t found.
• The Fix: Run pip install -U huggingface_hub to install the hf tool.
• The New Syntax: Remember that huggingface-cli is now deprecated in favor of hf. Log in using hf auth login.
• Next Step: To make life easier, set your HF_TOKEN environment variable in your RunPod pod settings so authentication works seamlessly across restarts.