Hugging Faceでモデルをダウンロードできない｜401・403・GatedRepoErrorの確認手順

Hugging Faceでモデル取得が401・403・GatedRepoErrorで止まったら、モデルを利用できるアカウントか、そのアカウントのトークンに権限があるか、実行中のPythonへ認証情報が届いているかを順に確認します。

ブラウザでモデルの紹介ページを開けても、ファイルを取得できるとは限りません。また、ブラウザでログインした状態は、そのままPythonや別のPCへ引き継がれるものではありません。

この記事はHugging Face Hub（モデルやデータを保管・共有するサービス）からのモデルファイルの取得を対象にします。推論APIの課金やGPUメモリ不足は別の問題として扱います。

401・403だけで原因を決めず、例外名も確認する

HTTPステータス（サーバーが返す処理結果の番号）に加え、例外名と失敗した処理を見ます。次の表は原因を確定するものではなく、確認を始める場所です。

公式仕様でもRepositoryNotFoundErrorは、リポジトリが見つからない場合と、privateでアクセスできない場合の両方を含みます。GatedRepoErrorは互換性のため、その派生クラスになっています。Hugging Face公式：例外のリファレンス

モデル取得に必要な3つの条件

トークンは、プログラムがアカウントに代わってアクセスするための認証情報です。アカウントがそのモデルを利用できない状態では、トークンを新しく作ってもモデルへの許可は得られません。

指定したファイルが存在し、通信や保存先が正常であることも必要ですが、認証エラーではこの3層を分けると調べやすくなります。

図：対象モデルで承認済みのAと、未承認のBを使う場合の比較です。Hugging Faceのgatedモデル・トークン仕様を基に独自作成。通信やファイル指定の成功を保証する図ではありません。

gatedモデルとprivateモデルの違い

gatedモデルは、ファイル取得の前に利用者の申請・同意などを求めるモデルです。公開ページが見えていても、ファイルへのアクセスには承認が必要なことがあります。申請には自動承認と手動承認があり、許可は利用者のアカウントに与えられます。Hugging Face公式：Gated models

privateモデルは、リポジトリ自体の可視性・アクセスが制限されています。所有者や組織から与えられた権限を確認します。privateとgatedでは、許可を得る仕組みが異なります。Hugging Face公式：Repository Settings

ブラウザで、対象モデルと申請したアカウントを確認する

モデルページのURLと、コードのrepo_id（組織名/モデル名などの識別子）を照合します。似た名前のモデル、別サイズ、派生版を取得しようとしていないか確認してください。

gatedモデルでは、コード側で使うアカウントと同じアカウントでブラウザへログインし、対象モデルの申請状態を確認します。モデルによって求められる情報や利用条件が異なるため、画面の案内に従います。申請中であれば、トークンを作り直しても承認待ちは解消しません。

たとえばアカウントAで承認を受け、PythonにはアカウントBのトークンを設定していると、ブラウザでは取得できてもPythonでは拒否されます。組織への所属だけで、自分が申請したアカウントを確認したことにはなりません。

承認はモデルの利用条件を確認する代わりにはならないため、目的に合うライセンスかもモデルページで確認します。Hugging Face公式：利用者によるgatedモデルへのアクセス

トークンは必要な読取権限に絞る

モデルをダウンロードする用途なら、書き込み権限を追加して直そうとする前に、対象モデルを読む権限を確認します。

fine-grained（対象や操作を細かく制限する方式）では、許可した範囲に今回のモデルが入っているかを確認します。モデルへのアクセス承認と、トークン側の範囲の両方が必要です。Hugging Face公式：User access tokens

モデルを取得する環境でログインを確認する

ターミナルではhf auth whoamiを使う

問題が起きる仮想環境を有効にしてから、ライブラリの場所と認証状態を確認します。未導入の場合は、その環境にhuggingface_hubをインストールします。既存プロジェクトに依存関係の制約がある場合は、その制約を維持してください。

python -m pip show huggingface_hub
hf auth whoami

ログインしていなければ、次のコマンドを実行します。

hf auth login
hf auth whoami

現行CLIではブラウザを使う方式やトークン入力の選択肢があります。インストール済みの版によって案内が違うため、hf auth login --helpと画面の指示を確認します。トークン文字列をコマンド行へ直接書かず、対話入力を使うとシェル履歴への記録を避けられます。古い解説にあるhuggingface-cli loginではなく、この記事では現行のhf auth loginを使います。Hugging Face公式：CLIの認証

whoamiで意図したアカウントが表示されたら、その認証情報でアカウントを識別できています。対象モデルの取得許可まで確認できたわけではないので、後述のファイル確認へ進みます。

Notebookでは、実行中のPythonから確認する

別のターミナルでログインしても、Notebookが違うユーザーや保存先を使っていれば結果が変わります。問題が起きるNotebookのセルで確認します。

import sys
import huggingface_hub
from huggingface_hub import whoami

print("Python:", sys.executable)
print("huggingface_hub:", huggingface_hub.__version__)
# トークンや応答全体を出さず、認証先のアカウント名だけを確認する。
account: dict = whoami()
print("Account:", account.get("name"))

未ログインなら、同じNotebookでfrom huggingface_hub import loginを実行し、login()の案内に従う方法もあります。認証情報がない・無効な場合、上のwhoami()は例外になります。共有時には例外ログをそのまま貼らず、秘密情報が含まれていないか確認してください。Hugging Face公式：Quickstartの認証

ログインしたのに直らないときはHF_TOKENと環境差を見る

保存し直したトークンより、環境変数が優先されることがある

通常のローカル環境では、環境変数HF_TOKENが設定されていると、保存済みトークンより優先されます。ログインし直したのに別アカウントのままなら、起動時に古い値が渡されていないかを調べます。

次のコードは、秘密値を表示せず、設定の有無とライブラリが使う保存場所を確認します。

import os
import sys
from huggingface_hub import constants

print("Python:", sys.executable)
print("HF_TOKEN configured:", bool(os.environ.get("HF_TOKEN")))
print("HF_HOME:", constants.HF_HOME)
print("HF_TOKEN_PATH:", constants.HF_TOKEN_PATH)
print("HF_HUB_OFFLINE:", os.environ.get("HF_HUB_OFFLINE", "未設定"))
print("HF_HUB_DISABLE_IMPLICIT_TOKEN:",
      os.environ.get("HF_HUB_DISABLE_IMPLICIT_TOKEN", "未設定"))

保存場所が表示されても、トークンが存在し、有効であるとまでは分かりません。HF_HOMEやHF_TOKEN_PATHを変更した環境では、以前のログイン保存先と違う場所を参照している可能性があります。

古いHF_TOKENを外す場合は、対象のシェル、IDE、コンテナ、Notebookの設定元で変更します。hf auth logoutだけでは、環境変数から渡されたトークンは解除されません。設定変更後は、新しいプロセスやNotebookのカーネルで確認し直すと、読み込み済みの設定との混同を避けられます。Hugging Face公式：環境変数

図：通常のローカル環境で、保存したAのトークンより環境変数のBが優先される例です。A/Bはアカウントを表す記号です。HF_HOMEなどを意図的に共有した構成や、ほかの認証方式の絶対的な優先順位を示すものではありません。公式の環境変数仕様を基に独自作成。

token=True・False・文字列は意味が違う

以下は、モデル取得で使うhf_hub_downloadの指定を整理したものです。

HF_HUB_DISABLE_IMPLICIT_TOKEN=1は、読み取りなどでのトークンの自動送信を抑えます。認証を使うことを明示したい診断ではtoken=Trueを指定します。ただし、この指定が対象モデルへの許可を追加するわけではありません。Hugging Face公式：暗黙のトークン送信、ファイル取得API

Colab・Windows・WSL・コンテナは、設定を分けて確認する

ColabではSecretsのHF_TOKENを使う方法があります。Secretの値をセルへ貼り付けたり表示したりせず、Notebookに利用を許可して使います。環境変数や保存済みトークンなども併存するため、設定した場所だけで判断せず、同じNotebookのwhoami()でアカウントを確認します。Hugging Face公式：Quickstart、認証情報の解決処理

対象モデルのファイルを、小さな確認から試す

重み全体を取得する前に、対象ファイルの情報を確認する

get_hf_file_metadata()は、ファイルのサイズなどの情報を問い合わせるAPI（プログラムから使う機能）です。モデルの重み本体をすべてダウンロードせず、対象ファイルへの問い合わせが通るかを確認できます。

次のコードはrepo_idとファイル名を入力して実行します。モデルページのファイル一覧で、実在するファイル名を確認してください。アクセス制限を調べたい場合は、READMEだけではなく、取得に失敗しているファイルそのものを指定します。

from huggingface_hub import get_hf_file_metadata, hf_hub_url
from huggingface_hub.errors import HfHubHTTPError, LocalTokenNotFoundError


def check_file(repo_id: str, filename: str, revision: str = "main") -> bool:
    """ファイル情報を問い合わせ、秘密値を含めず結果を表示する。

    Args: repo_idはモデルID、filenameはリポジトリ内のパス、revisionは版。
    Returns: メタデータを取得できればTrue、それ以外はFalse。
    Raises: KeyboardInterruptなどの中断は呼び出し元へ伝播する。
    Example: check_file("組織名/モデル名", "config.json")
    """
    try:
        url: str = hf_hub_url(repo_id, filename, revision=revision)
        metadata = get_hf_file_metadata(url, token=True)
    except LocalTokenNotFoundError:
        print("認証情報がありません。同じ環境のログイン設定を確認してください。")
        return False
    except HfHubHTTPError as error:
        status: int | None = (
            error.response.status_code if error.response is not None else None
        )
        # 応答全文やURLを出さず、診断に必要な分類だけを表示する。
        print("Exception:", type(error).__name__)
        print("HTTP status:", status)
        return False
    except Exception as error:
        # ネットワーク・設定エラーも、共有しやすい例外名だけを表示する。
        print("認証以外の可能性も確認:", type(error).__name__)
        return False
    print("メタデータ取得成功。ファイルサイズ:", metadata.size)
    return True


if __name__ == "__main__":
    target_repo: str = input("repo_id: ").strip()
    target_file: str = input("ファイル名: ").strip()
    check_file(target_repo, target_file)

メタデータ取得成功は、その時点でそのファイルの情報を取得できたことを表します。大きな重みの転送完了や、モデルの読み込み・推論の成功まで保証するものではありません。Hugging Face公式：ファイルメタデータの取得

例外を種類別に捕まえるコードへ拡張する場合は、GatedRepoErrorをRepositoryNotFoundErrorより先に処理します。逆順だと、派生クラスであるgatedの例外も一般的な「見つからない」側で処理されます。

設定ファイルの取得で、実際のダウンロードも確認する

対象モデルにconfig.jsonがあることを確認できたら、小さなファイルの取得を試します。次は対話入力したモデルIDから、そのファイルを取得する例です。

from huggingface_hub import hf_hub_download

repo_id: str = input("repo_id: ").strip()
file_path: str = hf_hub_download(
    repo_id=repo_id,
    filename="config.json",
    token=True,
    # 小さな設定ファイルで、キャッシュだけの成功と区別する。
    force_download=True,
)
print("設定ファイルを取得しました。")

config.jsonがないモデルでは、ファイル一覧にある小さなファイルを選びます。設定ファイルと重みで扱いが異なることもあるため、設定ファイルの成功だけで重み取得の問題がすべて解消したとは判断しません。

force_download=Trueは再取得を要求するため、確認に使う小さなファイルへ限定します。モデル全体を何度も取得する方法や、キャッシュディレクトリを丸ごと削除する方法から始める必要はありません。Hugging Face公式：Download files from the Hub

まだ失敗する場合は、どの段階まで成功したかで絞る

図：そのファイルの取得まで確認できても、別ファイルやモデル全体の読み込みは別途確認します。Hugging FaceのCLIとファイル取得仕様を基に独自作成した診断フローです。

ダウンロードは、Hubへの問い合わせの後、別の配信先へ接続する場合があります。失敗したURLのホスト名が違う場合は、その段階を記録すると調査先を絞れます。403という数字だけを見て、トークンを作り直し続けないようにします。Hugging Face公式：ファイル情報と配信先

相談時には、ライブラリの版、実行環境、公開してよいモデルIDとファイル名、例外名、HTTPステータス、どの確認まで成功したかを整理します。トークン、Authorizationヘッダー、署名付きURLのクエリ、非公開リポジトリ名は、公開ログへ載せないようにします。

モデル取得後に演算で止まる場合は、PyTorchのCPU・GPU混在エラーの対処法へ進みます。学習は動くものの遅い場合は、GPU使用率とDataLoaderの待ち時間を切り分ける方法を参照してください。

この記事で検証した範囲

2026年9月22日に公式資料を確認し、huggingface_hub 1.32.0の隔離環境で、トークン解決の挙動とCLIのヘルプを確認しました。トークン解決の検証にはダミー値だけを使い、Hubへは送信していません。

ネットワーク経由では、公開リポジトリopenai-community/gpt2のconfig.jsonを匿名で問い合わせ、665 bytesのファイルを取得しました。モデルの重みは取得していません。実トークンでのログイン、gated/privateモデルの取得、Colab上での動作は未検証です。これらの操作は公式仕様に基づく手順として記載しています。

参考資料

• Hugging Face：Gated models
• Hugging Face：User access tokens
• Hugging Face：Repository Settings
• huggingface_hub：CLI
• huggingface_hub：Quickstart
• huggingface_hub：Environment variables
• huggingface_hub：Utilities・例外
• huggingface_hub：Downloading files
• huggingface_hub：Download guide
• huggingface_hub：認証情報の解決処理