ModuleNotFoundError: No module named 'huggingface_hub' の原因と解決法

エラーメッセージ（全文）

ModuleNotFoundError: No module named 'huggingface_hub'

このエラーとは

ModuleNotFoundError: No module named 'huggingface_hub' は Python 開発でよく遭遇するエラーです。

想定環境: Windows / macOS / Linux

よく出る状況: pip install 前、venv 未有効化、パッケージ名 typo

よくある原因

• パッケージ 'huggingface_hub' がインストールされていない
• 仮想環境が有効化されておらず別の Python を使っている
• pip install 時のパッケージ名が異なる（PyPI 名と import 名の不一致）

確認手順（切り分け）

1. python -c "import sys; print(sys.executable)" で使用中の Python を確認
2. pip list | findstr /i huggingface_hub（Windows）または pip list | grep -i huggingface_hub
3. 仮想環境なら source venv/bin/activate または .\venv\Scripts\activate

解決方法

方法1: パッケージをインストール

使用中の Python に対して pip でインストールします。

pip install huggingface_hub
# または
python -m pip install huggingface_hub

方法2: 仮想環境を有効化してから再インストール

グローバルと venv の取り違えが最も多い原因です。

python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
pip install huggingface_hub

再発防止

• requirements.txt に依存関係を固定
• CI でも同じ venv 手順を使う

それでも直らないとき

バージョン情報（Python のバージョン、OS、実行コマンド）を添えて、エラーメッセージ全文と直前に変更した点を確認してください。ログの数行上にも原因の手がかりが残っていることが多いです。