Hub Python Library documentation
環境変数
環境変数
huggingface_hub は環境変数を使用して設定できます。
環境変数に不慣れな場合は、macOSおよびLinuxとWindowsに関する一般的な記事が参考になります。
このページでは、huggingface_hub に固有のすべての環境変数とその意味について説明します。
すべての環境変数は、
huggingface_hubのインポート時に読み込まれます。その後に適用された変更は反映されません。huggingface_hubをインポートする前に、環境変数を設定してください。
汎用
HF_INFERENCE_ENDPOINT
推論APIのベースURLを設定します。組織が推論APIに直接接続するのではなく、API Gatewayを介して接続している場合は、この変数を設定する必要がある場合があります。
デフォルト値は"/static-proxy?url=https%3A%2F%2Fapi-inference.huggingface.co"です。
HF_HOME
huggingface_hubがデータをローカルに保存する場所を設定します。具体的には、トークンとキャッシュがこのフォルダに保存されます。
XDG_CACHE_HOME が設定されていない場合、デフォルトは "~/.cache/huggingface" です。
HF_HUB_CACHE
Hubからのリポジトリ（モデル、データセット、スペース）をローカルにキャッシュする場所を設定します。
デフォルトは"$HF_HOME/hub"です（デフォルトでは"~/.cache/huggingface/hub"）。
HF_XET_CACHE
Xetがシャードキャッシュとアップロード用のステージングデータをローカルに保存する場所を設定します。詳細については、Xetのキャッシュを参照してください。
デフォルトは"$HF_HOME/xet"です（デフォルトでは"~/.cache/huggingface/xet"）。
HF_ASSETS_CACHE
assets を生成する下流のライブラリによって作成されるアセットのローカルキャッシュ先を設定します。これらのアセットには、前処理済みのデータ、GitHub からダウンロードされたファイル、ログなどが含まれます。
デフォルトは"$HF_HOME/assets"です（デフォルトでは"~/.cache/huggingface/assets"）。
HF_TOKEN
Hub への認証に使用する User Access Token を設定します。設定された場合、この値は、マシンに保存されているトークン（$HF_TOKEN_PATH、またはそれが設定されていない場合は "$HF_HOME/token"）を上書きします。
認証の詳細については、このセクションを参照してください。
HF_TOKEN_PATH
huggingface_hubがUser Access Tokenを保存する場所を設定します。デフォルトは"$HF_HOME/token"です（デフォルトでは~/.cache/huggingface/token）。
HF_HUB_VERBOSITY
huggingface_hubのロガーの冗長レベルを設定します。{"debug", "info", "warning", "error", "critical"}のいずれかである必要があります。
デフォルトは"warning"です。
詳細については、ロギングの参考資料を参照してください。
HF_HUB_ETAG_TIMEOUT
リポジトリからファイルをダウンロードする前に、最新のメタデータを取得する際にサーバーの応答を待機する秒数を定義する整数値です。リクエストがタイムアウトした場合、huggingface_hubはローカルにキャッシュされたファイルをデフォルトとして使用します。値を低く設定すると、ファイルがすでにキャッシュされている低速接続の環境でのワークフローが高速化されます。一方、値を高く設定すると、より多くのケースでメタデータ呼び出しの成功が保証されます。デフォルト値は10秒です。
HF_HUB_DOWNLOAD_TIMEOUT
ファイルのダウンロード時にサーバーの応答を待機する秒数を定義する整数値です。リクエストがタイムアウトすると、TimeoutError が発生します。接続が遅いマシンでは、より大きな値を設定することが有益です。一方、ネットワークが完全に遮断されている場合、より小さな値に設定することで、プロセスがより早く失敗します。デフォルト値は 10 秒です。
Xet
その他のXet環境変数
HF_XET_CHUNK_CACHE_SIZE_BYTES
この変数はもはや効果を持ちません。hf_xetはダウンロードにローカルチャンクキャッシュを使用しなくなっており、この変数を設定してもキャッシュは有効になりません。詳細はxet-core#715を参照してください。
HF_XET_SHARD_CACHE_SIZE_LIMIT
Xetシャードキャッシュのサイズをローカルで設定します。この値を大きくすると、キャッシュされたシャードファイル内で参照されているチャンクが再アップロードされなくなるため、アップロードの効率が向上します。ただし、デフォルトのソフトリミットはほとんどのワークロードで十分である可能性が高いことに注意してください。
デフォルト値は16000000000(16GB)です。
HF_XET_NUM_CONCURRENT_RANGE_GETS
この変数はもう使用されていません。hf_xet 1.3.0以降、ダウンロードの並行性は適応的に制御されます。
ブール値
以下の環境変数はブール値を期待します。値が{"1", "ON", "YES", "TRUE"}（大文字小文字を区別しない）のいずれかである場合、変数はTrueとみなされます。それ以外の値（または未定義）はFalseとみなされます。
HF_DEBUG
設定されている場合、huggingface_hubロガーのログレベルは DEBUG に設定されます。さらに、HF ライブラリによって発行されるすべてのリクエストは、デバッグと再現性を容易にするため、同等の cURL コマンドとして記録されます。
HF_HUB_OFFLINE
設定されている場合、Hugging Face Hub への HTTP 呼び出しは行われません。ファイルのダウンロードを試みると、キャッシュされたファイルのみがアクセスされます。キャッシュファイルが検出されない場合、エラーが発生します。ネットワークが遅く、ファイルの最新バージョンを気にしない場合に便利です。
環境変数としてHF_HUB_OFFLINE=1が設定されている状態でHfApiの任意のメソッドを呼び出すと、OfflineModeIsEnabled例外が発生します。
注: ファイルの最新バージョンがキャッシュされていても、hf_hub_download を呼び出すと、新しいバージョンが存在しないことを確認するために HTTP リクエストが送信されます。HF_HUB_OFFLINE=1 を設定すると、この呼び出しがスキップされ、読み込み時間が短縮されます。
オフラインモードが有効かどうかを確認するには、is_offline_mode()ヘルパーを使用できます。
HF_HUB_DISABLE_IMPLICIT_TOKEN
Hub へのすべてのリクエストに対して認証が必須であるわけではありません。例えば、"gpt2" モデルの詳細をリクエストする場合は、認証は不要です。ただし、ユーザーがログインしている場合、プライベートリポジトリやゲート付きリポジトリにアクセスする際のユーザー体験を向上させるため（HTTP 401 Unauthorized を決して返さないようにするため）、デフォルトでは常にトークンを送信します。プライバシー保護のため、HF_HUB_DISABLE_IMPLICIT_TOKEN=1 を設定することで、この動作を無効にできます。この場合、トークンは「書き込みアクセス」を伴う呼び出し（例: コミットを作成する）のときにのみ送信されます。
注意: トークンの暗黙的な送信を無効にすると、予期しない副作用が発生する可能性があります。例えば、Hub上のすべてのモデルをリスト表示しようとしても、プライベートモデルは表示されません。その場合、スクリプト内でtoken=True引数を明示的に渡す必要があります。
HF_HUB_DISABLE_PROGRESS_BARS
時間のかかるタスクでは、huggingface_hub はデフォルトで進捗バーを表示します（tqdm を使用）。HF_HUB_DISABLE_PROGRESS_BARS=1 を設定することで、すべての進捗バーを一度に無効にできます。
HF_HUB_DISABLE_SYMLINKS
設定されている場合、huggingface_hubはキャッシュ内にシンボリックリンクを作成しません。代わりに、ファイルはスナップショットディレクトリに直接複製または移動されます。これは、巨大なファイルがハードドライブ上で複製されてしまうという劣化モードでキャッシュディレクトリを動作させるための、上級ユーザー向けの機能です。
使用例として、異なるオペレーティングシステムで動作する複数のマシン間で共有ネットワークドライブ（NAS など）をHF_HUB_CACHEとして使用する場合が挙げられます。Linux で作成されたシンボリックリンクは、Windows 上で常に参照できるとは限らず、エラーの原因となります。HF_HUB_DISABLE_SYMLINKS=1を設定することで、ディスク容量の重複排除を犠牲にしながらも、この問題を回避できます。
HF_HUB_DISABLE_SYMLINKS_WARNING
Windows マシンを使用している場合は、開発者モードを有効にするか、huggingface_hub を管理者モードで実行することをお勧めします。そうしないと、huggingface_hub はキャッシュシステムにシンボリックリンクを作成できません。スクリプトの実行自体は可能ですが、一部の大きなファイルがハードドライブ上で重複して保存される可能性があるため、ユーザー体験が低下します。この動作について警告メッセージが表示されます。この警告を無効にするには、HF_HUB_DISABLE_SYMLINKS_WARNING=1 を設定してください。
詳細については、キャッシュの制限を参照してください。
HF_HUB_DISABLE_EXPERIMENTAL_WARNING
huggingface_hub の一部の機能は実験的です。これは、それらを使用することはできますが、将来のメンテナンスを保証するものではないことを意味します。特に、非推奨化のサイクルなしに、そのような機能の API や動作を更新する可能性があります。実験的な機能を使用すると、その旨を警告するメッセージが表示されます。実験的な機能の使用に伴う潜在的な問題のデバッグに問題がなければ、HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1 を設定して警告を無効にできます。
実験的な機能をご利用の場合は、ぜひお知らせください。フィードバックをいただければ、機能の設計や改善に役立てることができます。
HF_HUB_DISABLE_TELEMETRY
デフォルトでは、HF ライブラリ（transformers、datasets、gradio など）によって一部のデータが収集され、利用状況の監視、問題のデバッグ、機能の優先順位付けに活用されます。
各ライブラリは独自のポリシー（監視対象となる利用状況など）を定義しますが、コアの実装は huggingface_hub で行われます（send_telemetry を参照）。
環境変数としてHF_HUB_DISABLE_TELEMETRY=1を設定することで、テレメトリをグローバルに無効化できます。
HF_HUB_DISABLE_UPDATE_CHECK
デフォルトでは、hf CLI は起動時に PyPI で新しいリリースがあるかを確認します（最大24時間ごとに1回）。新しいリリースがある場合、stderr に1行の黄色い警告を表示し、hf update を実行することを提案します。このチェックは、開発版やプレリリース版ではすでに何もしない（no-op）状態です。
また、hf-cli スキルがインストールされ、実行中のバージョンによって生成されているかどうかを（最大で24時間ごとに1回、完全にローカルで）確認し、そうでない場合は hf skills add / hf skills update を提案します。このチェックはヒントを表示するだけで、スキルディレクトリには一切変更を加えません。
インストール済みのCLI拡張機能を実行する前に、GitHub上で新しいコミットが利用可能かどうかを確認します（拡張機能ごとに最大24時間ごとに1回）。利用可能な場合は、hf extensions update <name>の実行を提案します。hf extensions listも、そのLATEST列に同じ確認を使用します。
HF_HUB_DISABLE_UPDATE_CHECK=1 を設定すると、これらのリクエストをスキップし、すべてのヒントを無効にできます。オフラインの CI 環境や、シェル出力を静かにしたい場合に便利です。
HF_HUB_DISABLE_XET
hf-xet の使用を無効にする設定です。Python 環境に hf-xet が利用可能であっても、これを無効にできます。hf-xet は検出された場合自動的に使用されるため、この設定により明示的にその使用を無効にできます。Xet を無効にしている場合は、Xet が動作しない理由を理解するために、問題を報告し、診断情報を含めることを検討してください。
HF_HUB_ENABLE_HF_TRANSFER
これは非推奨の環境変数です。 Hugging Face Hub が完全に Xet ストレージバックエンドで動作するようになったため、すべてのファイル転送は
hf-xetバイナリパッケージを介して行われます。このパッケージはチャンクベースの重複排除戦略を用いて効率的な転送を提供し、huggingface_hubとシームレスに統合されています。 つまり、hf_transferはもはや使用できません。より高いパフォーマンスに関心がある場合は、HF_XET_HIGH_PERFORMANCEセクション をご覧ください。
HF_HUB_DISABLE_SHARED_BLOBS
1に設定すると、キャッシュ全体で共有されるブロブストアが無効になります。デフォルトでは、正常にダウンロードされた Xet ファイルは <CACHE_DIR>/blobs/<prefix>/<xet_hash> に保存され、リポジトリのキャッシュにシンボリックリンクとして配置されるため、同一のファイルはリポジトリをまたいでディスク上に1回のみ保存され、再取得せずに再利用できます。この最適化はデフォルトで有効ですが、Xet が利用できない場合（HF_HUB_DISABLE_XET=1 が設定されている場合など）や、ローカルでシンボリックリンクがサポートされていない場合は無効になります。そのような場合は、リポジトリローカルの通常のストレージに静かにフォールバックします。詳細は キャッシュのガイド を参照してください。
HF_XET_HIGH_PERFORMANCE
hf-xetを、マシン上のネットワークおよびディスクリソースを最大限に活用するための増強設定で動作させます。ハイパフォーマンスモードを有効にすると、このマシンのネットワーク帯域幅を飽和させ、並列アップロード/ダウンロード処理にすべてのCPUコアを利用しようとします。
これは従来のHF_HUB_ENABLE_HF_TRANSFER=1環境変数に相当するものですが、hf-xetに適用されるものです。
Xetストレージとhf_xetの利点について詳しく知るには、このセクションを参照してください。
HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY
この変数はもはや使用されていません。hf_xet 1.3.0 以降、ファイルは常にローカルディスクにシーケンシャルに書き込まれます（v1.3.0 のファイルライターを参照）。
非推奨の環境変数
Hugging Faceエコシステム内のすべての環境変数を標準化するため、一部の環境変数は非推奨とマークされています。これらは引き続き機能しますが、その代替変数よりも優先されなくなりました。以下の表に、非推奨の環境変数とそれに対応する代替変数を示します。
| 非推奨の変数 | 置き換え |
|---|---|
HUGGINGFACE_HUB_CACHE | HF_HUB_CACHE |
HUGGINGFACE_ASSETS_CACHE | HF_ASSETS_CACHE |
HUGGING_FACE_HUB_TOKEN | HF_TOKEN |
外部ツールから
一部の環境変数はhuggingface_hubに固有のものではありませんが、設定されている場合は考慮されます。
DO_NOT_TRACK
ブール値。HF_HUB_DISABLE_TELEMETRY と同等です。true に設定すると、Hugging Face の Python エコシステム全体（transformers、diffusers、gradio など）でテレメトリがグローバルに無効になります。詳細は https://donottrack.sh/ を参照してください。
NO_COLOR
ブール値。設定すると、hf CLI は ANSI カラーを出力しません。
no-color.orgを参照してください。
XDG_CACHE_HOME
HF_HOMEが設定されていない場合のみ使用されます!
Linuxマシンにおいて、ユーザー固有の非必須（キャッシュ）データをどこに書き込むかを設定するデフォルトの方法です。
HF_HOMEが設定されていない場合、デフォルトのホームは"~/.cache/huggingface"ではなく、"$XDG_CACHE_HOME/huggingface"になります。