Basic problem getting huggingface_cli

Beginners
1

hello,

i’m a systems admin administering a machine running alma linux 9.6, in order to provide support for our users, who are python developers. i have a problem trying to run the huggingface cli. we’ve just installed a fresh new python, upgrading to 3.9 to 3.13.10. the error i get is :

$ huggingface-cli
Traceback (most recent call last):
  File "/usr/local/bin/huggingface-cli", line 3, in <module>
    from huggingface_hub.commands.huggingface_cli import main
ModuleNotFoundError: No module named 'huggingface_hub.commands'

looking at the directory structure, i can see that there is, indeed, no commands subdirectory.
here is some more information :

$ set | grep ^PY
PYTHONPATH=/usr/local/lib/python3.13:/usr/local/lib/python3.13/site-packages
PYTHONUSERBASE=/usr/local/lib/python3.13

$ python3 -V
Python 3.13.10

$ pip3 -V
pip 25.3 from /usr/local/lib/python3.13/site-packages/pip (python 3.13)

huggingface was not included in 3.13, so i installed it. the install didn’t solve the problem, so after checking a few things, i did a reinstall. in case it’s helpful, here is the output of my install :

$ pip3 install --cache-dir=/data/tmp --upgrade --force-reinstall huggingface_hub
Collecting huggingface_hub
  Downloading huggingface_hub-1.3.5-py3-none-any.whl.metadata (13 kB)
Collecting filelock (from huggingface_hub)
  Using cached filelock-3.20.3-py3-none-any.whl.metadata (2.1 kB)
Collecting fsspec>=2023.5.0 (from huggingface_hub)
  Using cached fsspec-2026.1.0-py3-none-any.whl.metadata (10 kB)
Collecting hf-xet<2.0.0,>=1.2.0 (from huggingface_hub)
  Using cached hf_xet-1.2.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (4.9 kB)
Collecting httpx<1,>=0.23.0 (from huggingface_hub)
  Using cached httpx-0.28.1-py3-none-any.whl.metadata (7.1 kB)
Collecting packaging>=20.9 (from huggingface_hub)
  Downloading packaging-26.0-py3-none-any.whl.metadata (3.3 kB)
Collecting pyyaml>=5.1 (from huggingface_hub)
  Downloading pyyaml-6.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.metadata (2.4 kB)
Collecting shellingham (from huggingface_hub)
  Using cached shellingham-1.5.4-py2.py3-none-any.whl.metadata (3.5 kB)
Collecting tqdm>=4.42.1 (from huggingface_hub)
  Using cached tqdm-4.67.1-py3-none-any.whl.metadata (57 kB)
Collecting typer-slim (from huggingface_hub)
  Using cached typer_slim-0.21.1-py3-none-any.whl.metadata (16 kB)
Collecting typing-extensions>=4.1.0 (from huggingface_hub)
  Using cached typing_extensions-4.15.0-py3-none-any.whl.metadata (3.3 kB)
Collecting anyio (from httpx<1,>=0.23.0->huggingface_hub)
  Using cached anyio-4.12.1-py3-none-any.whl.metadata (4.3 kB)
Collecting certifi (from httpx<1,>=0.23.0->huggingface_hub)
  Using cached certifi-2026.1.4-py3-none-any.whl.metadata (2.5 kB)
Collecting httpcore==1.* (from httpx<1,>=0.23.0->huggingface_hub)
  Using cached httpcore-1.0.9-py3-none-any.whl.metadata (21 kB)
Collecting idna (from httpx<1,>=0.23.0->huggingface_hub)
  Using cached idna-3.11-py3-none-any.whl.metadata (8.4 kB)
Collecting h11>=0.16 (from httpcore==1.*->httpx<1,>=0.23.0->huggingface_hub)
  Using cached h11-0.16.0-py3-none-any.whl.metadata (8.3 kB)
Collecting click>=8.0.0 (from typer-slim->huggingface_hub)
  Using cached click-8.3.1-py3-none-any.whl.metadata (2.6 kB)
Downloading huggingface_hub-1.3.5-py3-none-any.whl (536 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 536.7/536.7 kB 26.7 MB/s  0:00:00
Using cached hf_xet-1.2.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.3 MB)
Using cached httpx-0.28.1-py3-none-any.whl (73 kB)
Using cached httpcore-1.0.9-py3-none-any.whl (78 kB)
Using cached fsspec-2026.1.0-py3-none-any.whl (201 kB)
Using cached h11-0.16.0-py3-none-any.whl (37 kB)
Downloading packaging-26.0-py3-none-any.whl (74 kB)
Downloading pyyaml-6.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (801 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 801.6/801.6 kB 30.4 MB/s  0:00:00
Using cached tqdm-4.67.1-py3-none-any.whl (78 kB)
Using cached typing_extensions-4.15.0-py3-none-any.whl (44 kB)
Using cached anyio-4.12.1-py3-none-any.whl (113 kB)
Using cached idna-3.11-py3-none-any.whl (71 kB)
Using cached certifi-2026.1.4-py3-none-any.whl (152 kB)
Using cached filelock-3.20.3-py3-none-any.whl (16 kB)
Using cached shellingham-1.5.4-py2.py3-none-any.whl (9.8 kB)
Using cached typer_slim-0.21.1-py3-none-any.whl (47 kB)
Using cached click-8.3.1-py3-none-any.whl (108 kB)
Installing collected packages: typing-extensions, tqdm, shellingham, pyyaml, packaging, idna, hf-xet, h11, fsspec, filelock, click, certifi, typer-slim, httpcore, anyio, httpx, huggingface_hub
  Attempting uninstall: typing-extensions
    Found existing installation: typing_extensions 4.15.0
    Uninstalling typing_extensions-4.15.0:
      Successfully uninstalled typing_extensions-4.15.0
  Attempting uninstall: tqdm
    Found existing installation: tqdm 4.67.1
    Uninstalling tqdm-4.67.1:
      Successfully uninstalled tqdm-4.67.1
  Attempting uninstall: shellingham
    Found existing installation: shellingham 1.5.4
    Uninstalling shellingham-1.5.4:
      Successfully uninstalled shellingham-1.5.4
  Attempting uninstall: pyyaml
    Found existing installation: PyYAML 6.0.3
    Uninstalling PyYAML-6.0.3:
      Successfully uninstalled PyYAML-6.0.3
  Attempting uninstall: packaging
    Found existing installation: packaging 26.0
    Uninstalling packaging-26.0:
      Successfully uninstalled packaging-26.0
  Attempting uninstall: idna
    Found existing installation: idna 3.11
    Uninstalling idna-3.11:
      Successfully uninstalled idna-3.11
  Attempting uninstall: hf-xet
    Found existing installation: hf-xet 1.2.0
    Uninstalling hf-xet-1.2.0:
      Successfully uninstalled hf-xet-1.2.0
  Attempting uninstall: h11
    Found existing installation: h11 0.16.0
    Uninstalling h11-0.16.0:
      Successfully uninstalled h11-0.16.0
  Attempting uninstall: fsspec
    Found existing installation: fsspec 2026.1.0
    Uninstalling fsspec-2026.1.0:
      Successfully uninstalled fsspec-2026.1.0
  Attempting uninstall: filelock
    Found existing installation: filelock 3.20.3
    Uninstalling filelock-3.20.3:
      Successfully uninstalled filelock-3.20.3
  Attempting uninstall: click
    Found existing installation: click 8.3.1
    Uninstalling click-8.3.1:
      Successfully uninstalled click-8.3.1
  Attempting uninstall: certifi
    Found existing installation: certifi 2026.1.4
    Uninstalling certifi-2026.1.4:
      Successfully uninstalled certifi-2026.1.4
  Attempting uninstall: typer-slim
    Found existing installation: typer-slim 0.21.1
    Uninstalling typer-slim-0.21.1:
      Successfully uninstalled typer-slim-0.21.1
  Attempting uninstall: httpcore
    Found existing installation: httpcore 1.0.9
    Uninstalling httpcore-1.0.9:
      Successfully uninstalled httpcore-1.0.9
  Attempting uninstall: anyio
    Found existing installation: anyio 4.12.1
    Uninstalling anyio-4.12.1:
      Successfully uninstalled anyio-4.12.1
  Attempting uninstall: httpx
    Found existing installation: httpx 0.28.1
    Uninstalling httpx-0.28.1:
      Successfully uninstalled httpx-0.28.1
  Attempting uninstall: huggingface_hub
    Found existing installation: huggingface_hub 1.3.5
    Uninstalling huggingface_hub-1.3.5:
      Successfully uninstalled huggingface_hub-1.3.5
Successfully installed anyio-4.12.1 certifi-2026.1.4 click-8.3.1 filelock-3.20.3 fsspec-2026.1.0 h11-0.16.0 hf-xet-1.2.0 httpcore-1.0.9 httpx-0.28.1 huggingface_hub-1.3.5 idna-3.11 packaging-26.0 pyyaml-6.0.3 shellingham-1.5.4 tqdm-4.67.1 typer-slim-0.21.1 typing-extensions-4.15.0

do i need to download something else in order to get the commands?

or, on a broader note, does anyone have an idea about why this isn’t working and how i can fix it?

thanks very much

NOTA - please don’t suggest something like, “well, why not just create a virtual environment”. it has to work under this environment.

1 Like
2

due to change in v1.x?

What’s actually broken (in your specific environment)

You are not missing a download or a “commands” add-on. You are running a stale huggingface-cli console script (/usr/local/bin/huggingface-cli) that was generated by an older huggingface_hub layout and now points at an import path that no longer exists:

from huggingface_hub.commands.huggingface_cli import main

As of the huggingface_hub v1.0 migration, Hugging Face explicitly states the deprecated huggingface-cli has been removed and the supported CLI is hf. (Hugging Face)

That is why you do not see huggingface_hub/commands/ in the installed package: in the modern world, you’re expected to use hf, and the legacy module path your script imports is gone. (Hugging Face)

This “Python upgrade → old wrapper script survives → import error” pattern is common; there’s even a January 2026 report with essentially the same traceback after upgrading Python. (Welcome to python-forum.io)

Why reinstalling huggingface_hub didn’t fix it

Even after pip install --force-reinstall huggingface_hub, pip does not necessarily delete/replace unrelated old executables if the new version no longer provides that entrypoint.

In your case:

  • Old world: huggingface-cli existed and imported huggingface_hub.commands…
  • New world (v1.0+): huggingface-cli is removed; hf is the CLI (Hugging Face)

So the old /usr/local/bin/huggingface-cli can remain on disk, still pointing at an import that’s no longer valid.

What to do on AlmaLinux (system-wide, no venv)

Step 1 — Confirm the supported CLI (hf) is present

The official CLI docs describe hf as the CLI and show hf --help as the basic health check. (Hugging Face)

Run:

command -v hf
hf --help
hf version

If hf works: your install is basically fine. The problem is only the legacy huggingface-cli wrapper.

If hf is missing: it’s usually PATH / install-target mismatch; the CLI docs explicitly call out that hf missing means “check installation.” (Hugging Face)

Step 2 — Prove you’re executing a stale wrapper

Run:

which -a huggingface-cli
head -n 20 /usr/local/bin/huggingface-cli

You’ll see the from huggingface_hub.commands... import line, confirming it’s an old entrypoint.

Step 3 — Fix it while preserving existing user workflows

Option A (recommended): keep huggingface-cli as a compatibility shim to hf

This is the best sysadmin move when users/scripts still call huggingface-cli.

sudo mv -f /usr/local/bin/huggingface-cli /usr/local/bin/huggingface-cli.bak.$(date +%F)

sudo tee /usr/local/bin/huggingface-cli >/dev/null <<'EOF'
#!/usr/bin/env bash
exec hf "$@"
EOF

sudo chmod 0755 /usr/local/bin/huggingface-cli

Result: users can keep typing huggingface-cli …, but it runs the supported hf ….

Context: Hugging Face explicitly replaced legacy huggingface-cli with the resource/action style hf auth login, hf download, hf upload, hf cache …, etc. (Hugging Face)

Option B: remove the stale wrapper and standardize on hf

This aligns with the v1.0 migration guidance (“huggingface-cli removed; use hf”). (Hugging Face)

If you truly need the old huggingface-cli implementation (not just the name)

If you have automation that depends on the legacy subcommands/behavior (not just “a command named huggingface-cli”), then you must pin huggingface_hub to a pre-v1.0 version where that CLI existed and was documented as huggingface-cli. For example, the v0.33 docs document the old CLI. (Hugging Face)

That tradeoff is:

  • :white_check_mark: old CLI behavior
  • :cross_mark: you give up v1.x changes and newer CLI features described in the v1.0 docs/blog (Hugging Face)

Two system-level pitfalls worth checking (because you’re a shared host)

1) “Wrong pip / wrong Python” drift

On multi-Python systems, always prefer:

python3 -m pip install ...

This avoids the “script wrapper” mismatch class of problems documented by pip users. (Stack Overflow)

2) Multiple huggingface-cli on PATH

You already have /usr/local/bin/huggingface-cli. Make sure there isn’t another earlier in PATH:

which -a huggingface-cli

What I would implement as the admin baseline

  1. Standardize on hf as the supported CLI (per Hugging Face docs). (Hugging Face)
  2. Install the compatibility shim so legacy calls to huggingface-cli don’t break.
  3. Add an internal note showing the modern equivalents (auth, download/upload, cache). The v1.0 blog post gives concise examples. (Hugging Face)

This makes your environment stable across future upgrades: when upstream removes/renames an entrypoint, stale scripts stop being “time bombs” and become a controlled compatibility layer.

3

@John6666 THANK YOU for this awesome reply. :grinning_face:
after literally days and days of struggling with this problem through different versions of python and other py packages, i’m now hopeful i can resolve this thing. maybe by the end of today (!) if i’m not way-laid.

1 Like