「HuggingFaceからモデルをダウンロードしたいけど、どのコマンドを使えばいいの？」という疑問に直接お答えします。結論、2026年6月時点では hf コマンドを使います。旧来の huggingface-cli は huggingface_hub 1.19.0 で非推奨になり、hf に置き換わっています。
本記事では Ubuntu 24.04 LTS（Docker公式イメージ）で実際にインストールして動かした結果を載せています。バージョンはすべて 2026-06-13 時点の実測値です。
この記事のポイント
- インストールは
pip install huggingface_hubの1コマンド。Ubuntu の apt リポジトリには含まれていない - 旧コマンド
huggingface-cliは非推奨。新コマンドはhf（huggingface_hub 1.19.0 以降） - Ubuntu 22.04 / 24.04 どちらでも huggingface_hub 1.19.0 が同じ手順でインストールできることを実測済み
- モデルのダウンロードは
hf download モデルID。--dry-runで事前確認できる - キャッシュは
~/.cache/huggingface/hubに保存。HF_HUB_CACHE環境変数で変更できる
目次
- HuggingFace CLIとは（
hfコマンドの全体像） - インストール前の確認事項
- インストール手順（Ubuntu 24.04 / 22.04）
- 基本コマンドの使い方
- モデルのダウンロード
- キャッシュ管理
- よくあるエラーと解決策
- まとめ
HuggingFace CLIとは
HuggingFace Hub CLI は、Hugging Face Hub（モデル・データセット・スペースのホスティングサービス）をコマンドラインから操作するためのツールです。Pythonパッケージ huggingface_hub をインストールすると hf コマンドが使えるようになります。
できることの例:
- LLM・画像生成モデルなどを一括ダウンロード
- ローカルのモデルを Hub にアップロード
- Hubのモデル・データセット一覧を検索・表示
- キャッシュの管理（確認・削除）
- Hugging Face アカウントへのログイン管理
2026年6月時点の重要な変更点
huggingface_hub 1.19.0 から huggingface-cli コマンドが非推奨（deprecated）になりました。実際に実行すると「Warning: `huggingface-cli` is deprecated and no longer works. Use `hf` instead.」と表示されます。旧コマンド名でネット検索すると古い情報が出てきますが、現在は hf コマンドを使うのが正しい方法です。
旧コマンド huggingface-cli（バージョン0.21.4頃）では login・download・upload・scan-cache の4コマンドのみでしたが、新しい hf では auth・cache・download・models・datasets・upload・repos・spaces・jobs・webhooks など18種類のサブコマンドが使えます。
インストール前の確認事項
手順1：前提環境を確認する
本記事で検証した環境です:
| 項目 | 値 |
|---|---|
| OS | Ubuntu 24.04 LTS（Docker公式イメージ ubuntu:24.04） |
| Python | 3.12.3（Ubuntu 24.04 標準） |
| huggingface_hub | 1.19.0（2026-06-13 時点の最新版） |
| 新CLIコマンド | hf（旧 huggingface-cli は非推奨） |
Ubuntu 22.04 でも同じ手順でインストールできます（Python バージョンが 3.10.12 になりますが、動作は同じです）。
手順2：Python と pip の確認
Python 3.12.3
$ python3 -m pip –version
pip 24.0 from /usr/lib/python3/dist-packages/pip (python 3.12)
注意：apt には huggingface_hub がありません
apt-cache search huggingface を実行しても何もヒットしません。Ubuntu 24.04 の公式リポジトリには python3-huggingface-hub パッケージが存在しないため、必ず pip でインストールしてください。
インストール手順
手順1：venv（仮想環境）を作る
システム全体のPythonを汚さないために、venv（仮想環境）の使用を強く推奨します。
Reading package lists… Done
python3 is already the newest version (3.12.3-0ubuntu2).
$ python3 -m venv ~/hf_env
$ source ~/hf_env/bin/activate
(hf_env) $
手順2：huggingface_hub をインストールする
Collecting huggingface_hub
Downloading huggingface_hub-1.19.0-py3-none-any.whl (693 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 693.4/693.4 kB 32.7 MB/s eta 0:00:00
Collecting click>=8.4.0, filelock, fsspec, httpx, tqdm, typer …
Successfully installed huggingface_hub-1.19.0 typer-0.25.1 rich-15.0.0
… and 16 dependency packages
インストールされる主な依存パッケージ：click・filelock・fsspec・httpx・tqdm・typer・rich・hf-xet など16パッケージ。hf-xet はXet Storageプロトコル（大容量ファイルの高速転送用）のバイナリです。
手順3：インストールを確認する
1.19.0
(hf_env) $ pip show huggingface_hub | grep -E ‘(Name|Version)’
Name: huggingface_hub
Version: 1.19.0
hf --version で 1.19.0 が表示されれば成功です。
正直、「huggingface-cli のインストール方法」で検索すると旧コマンドの情報ばかり出てきます。実際にコンテナで動かしてみて、Warning: `huggingface-cli` is deprecated と出たときに初めて気づきました。公式ドキュメントも追いつくのが遅れがちなので、このような実測記事が役に立つと思っています。
基本コマンドの使い方
①hf –help でコマンド一覧を確認する
hf --help でサブコマンドの一覧が表示されます。
Usage: hf [OPTIONS] COMMAND [ARGS]…
Hugging Face Hub CLI
Main commands:
auth Manage authentication (login, logout, etc.)
cache Manage local cache directory
download Download files from the Hub
models Interact with models on the Hub
datasets Interact with datasets on the Hub
upload Upload a file or a folder to the Hub
repos Manage repos on the Hub
spaces Interact with spaces on the Hub
jobs Run and manage Jobs on the Hub
…
Help commands:
env Print information about the environment
version Print hf version
②hf env で環境情報を確認する
hf env は現在の環境情報を一覧表示します。問題が起きたときのデバッグや、キャッシュ場所の確認に便利です。
– huggingface_hub version: 1.19.0
– Platform: Linux-6.8.0-generic-x86_64-with-glibc2.39
– Python version: 3.12.3
– Has saved token ?: False
– Installation method: pip
– httpx: 0.28.1
– hf_xet: 1.5.1
– HF_HUB_CACHE: /root/.cache/huggingface/hub
– HF_HUB_OFFLINE: False
– HF_HUB_DISABLE_TELEMETRY: False
特に重要なのは HF_HUB_CACHE の値です。デフォルトは ~/.cache/huggingface/hub。VPSのOSディスクが小さい場合は、大容量のデータディスクに変更しましょう。
$ export HF_HUB_CACHE=/mnt/data/hf_cache
$ hf download gpt2
# /mnt/data/hf_cache に保存される
③hf auth login でログインする
公開モデルは認証なしでダウンロードできますが、Llama 3 など利用規約への同意が必要なモデルはトークンが必要です。
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_|
Enter your token (input will not be visible): …
Login successful. Your token has been saved to /root/.cache/huggingface/token
$ hf auth whoami
your_username
トークンは Hugging Face の設定ページ（Settings → Access Tokens）で発行できます。Read 権限のあるトークンで十分です。
モデルのダウンロード
①ドライランで確認する
いきなりダウンロードするのではなく、--dry-run で事前確認するのがおすすめです。実際に試してみると：
[dry-run] Will download 1 files (out of 1) totalling 665.0.
FILE SIZE
———– —–
config.json 665.0
GPT-2 の config.json は 665 バイト（0.7KB）と非常に小さいですが、大型LLMでは数十GBになります。--dry-run でファイル数と合計サイズを確認してからダウンロードしましょう。
②モデル全体をダウンロードする
$ hf download gpt2
Fetching 9 files: 100%|████████████████| 9/9 [00:15<00:00]
/root/.cache/huggingface/hub/models–gpt2/snapshots/607a30d7…
# 特定ファイルだけダウンロード
$ hf download gpt2 config.json tokenizer.json
Fetching 2 files: 100%|████████████████| 2/2 [00:03<00:00]
# glob パターンで絞り込み（safetensors のみ）
$ hf download meta-llama/Llama-3.2-1B –include “*.safetensors”
③ローカルディレクトリに直接保存する
デフォルトのキャッシュ形式（シンボリックリンク方式）ではなく、指定ディレクトリに直接ファイルとして保存したい場合は --local-dir を使います。
Fetching 9 files: 100%|████████████████| 9/9 [00:12<00:00]
./models/gpt2
$ ls ./models/gpt2
config.json generation_config.json merges.txt model.safetensors
tokenizer.json tokenizer_config.json vocab.json
キャッシュ vs ローカルディレクトリ
- デフォルト（キャッシュ）: 同じモデルを複数箇所から使う場合に重複保存を防げる。シンボリックリンクで管理される
--local-dir: DockerコンテナやCI環境でモデルを持ち込む際に管理しやすい。実ファイルが配置される- VPS運用では、モデルを複数のツール（Ollama・Python・FastAPI）で共有する場合は
--local-dirの方が扱いやすいことが多い
④データセットのダウンロード
$ hf download rajpurkar/squad –type dataset –local-dir ./datasets/squad
Fetching 5 files: 100%|████████████████| 5/5 [00:08<00:00]
./datasets/squad
キャッシュ管理
①キャッシュの確認
REPO ID REPO TYPE REVISION SIZE ON DISK NB FILES LAST_ACCESSED LAST_MODIFIED REFS
——— ——— ——————- ————- ——— ————– ————– —-
gpt2 model 607a30d783dfa663… 475.0M 9 1 hour ago 1 hour ago main
Done in 0.0s. Scanned 1 repo(s) for a total of 475.0M.
注意：キャッシュが空の状態で hf cache ls を実行すると
Error: Cache directory not found: /root/.cache/huggingface/hub と表示されます。これはエラーではなく、まだ何もダウンロードしていないだけです。一度でもダウンロードするとキャッシュディレクトリが作成されます。
②不要なキャッシュを削除する
$ hf cache prune
Deleted 0 blobs totalling 0 MB.
# 特定リポジトリの完全削除
$ hf cache rm gpt2
Deleted model gpt2. 475.0M freed.
よくあるエラーと解決策
エラー1：command not found: hf
venv を有効化していない、またはインストール先のパスが通っていない場合に起こります。
bash: hf: command not found
# 解決：venv を有効化してから実行
$ source ~/hf_env/bin/activate
$ hf –version
1.19.0
# またはフルパスで実行
$ ~/hf_env/bin/hf –version
1.19.0
エラー2：huggingface-cli is deprecated の警告
Warning: `huggingface-cli` is deprecated and no longer works. Use `hf` instead.
Hint: Install `hf`:
Using pip: pip install huggingface_hub
# 解決：hf コマンドを使う
$ hf –help
Usage: hf [OPTIONS] COMMAND [ARGS]…
エラー3：Not logged in（gated model）
Error: 401 Client Error: Unauthorized for url: …
# 解決：先にログインする
$ hf auth login
Login successful.
$ hf download meta-llama/Llama-3.2-1B-Instruct
エラー4：Cache directory not found
hf cache ls を初回実行したときに出るエラーです。キャッシュディレクトリが存在しない（まだ何もダウンロードしていない）ことを示しているだけなので、気にしなくて大丈夫です。
まとめ
Ubuntu 24.04 での HuggingFace CLI 導入手順と主要コマンドをまとめます。
- インストールは
pip install huggingface_hub（apt リポジトリには存在しない） - コマンドは
hf（旧huggingface-cliは huggingface_hub 1.19.0 で非推奨に） - Ubuntu 22.04 / 24.04 どちらでも同手順。2026年4月以降のサポートを考えると Ubuntu 24.04 LTS 推奨
- ダウンロード前に
hf download --dry-runでファイル数・サイズを確認する習慣を - キャッシュは
~/.cache/huggingface/hub。VPSのディスクが小さいときはHF_HUB_CACHE環境変数で変更 - ゲートモデル（Llama等）は
hf auth loginで事前認証が必要
次のステップ
- ダウンロードしたモデルを
transformersライブラリで使いたい場合はpip install transformersも必要 - Ollama でモデルを動かすことも可能。HuggingFaceからGGUFファイルをダウンロードして
ollama createでロードできます - モデルを継続的に使うなら、ディスク容量に余裕のあるVPSがあると便利です
本格的にAI/MLのワークロードをVPSで動かしたいなら、GPU付きインスタンスが選べる も参考にしてください。
コメント