# 環境変数

`huggingface_hub` は環境変数を使用して設定できます。

環境変数に不慣れな場合は、[macOSおよびLinux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/)と[Windows](https://phoenixnap.com/kb/windows-set-environment-variable)に関する一般的な記事が参考になります。

このページでは、`huggingface_hub` に固有のすべての環境変数とその意味について説明します。

> [!TIP]
> すべての環境変数は、`huggingface_hub`のインポート時に読み込まれます。その後の変更は反映されません。`huggingface_hub`をインポートする前に、環境変数を設定してください。

## 汎用

### HF_INFERENCE_ENDPOINT

推論APIのベースURLを設定します。組織が推論APIに直接接続するのではなく、API Gatewayを介して接続している場合は、この変数を設定する必要がある場合があります。

デフォルト値は`"https://api-inference.huggingface.co"`です。

### HF_HOME

`huggingface_hub`がデータをローカルに保存する場所を設定します。具体的には、トークンとキャッシュがこのフォルダに保存されます。

[XDG_CACHE_HOME](#xdgcachehome) が設定されていない場合、デフォルトは `"~/.cache/huggingface"` です。

### HF_HUB_CACHE

Hub からのリポジトリ（モデル、データセット、スペース）をローカルにキャッシュする場所を設定します。

デフォルトは`"$HF_HOME/hub"`です（デフォルトでは`"~/.cache/huggingface/hub"`）。

### HF_XET_CACHE

Xetがシャードキャッシュとアップロード用のステージングデータをローカルに保存する場所を設定します。詳細については、[Xetのキャッシュ](../guides/manage-cache#xet-caching)を参照してください。

デフォルトは`"$HF_HOME/xet"`です（デフォルトでは`"~/.cache/huggingface/xet"`）。

### HF_ASSETS_CACHE

[assets](../guides/manage-cache#caching-assets) を生成する下流のライブラリによってローカルにキャッシュされる場所を設定します。これらのアセットには、前処理されたデータ、GitHub からダウンロードされたファイル、ログなどが含まれます。

デフォルトは`"$HF_HOME/assets"`です（デフォルトでは`"~/.cache/huggingface/assets"`）。

### HF_TOKEN

Hub への認証に使用する User Access Token を設定します。設定されている場合、この値はマシンに保存されているトークン（`$HF_TOKEN_PATH`、またはそれが設定されていない場合は `"$HF_HOME/token"`）を上書きします。

認証の詳細については、[このセクション](../quick-start#authentication)を参照してください。

### 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"`です。

詳細については、[ロギングの参考資料](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity)を参照してください。

### HF_HUB_ETAG_TIMEOUT

リポジトリからファイルをダウンロードする前に、最新のメタデータを取得する際にサーバーの応答を待機する秒数を定義する整数値です。リクエストがタイムアウトした場合、`huggingface_hub`はローカルにキャッシュされたファイルをデフォルトとして使用します。値を低く設定すると、ファイルがすでにキャッシュされている低速接続の環境でのワークフローが高速化されます。一方、値を高く設定すると、より多くのケースでメタデータ呼び出しの成功が保証されます。デフォルト値は10秒です。

### HF_HUB_DOWNLOAD_TIMEOUT

ファイルのダウンロード時にサーバーの応答を待機する秒数を定義する整数値です。リクエストがタイムアウトすると、TimeoutError が発生します。接続が遅いマシンでは、より大きな値を設定することが有益です。一方、ネットワークが完全に遮断されている場合、より小さな値に設定することで、プロセスがより早く失敗します。デフォルト値は 10 秒です。

## Xet 

### その他のXet環境変数
* [`HF_HUB_DISABLE_XET`](../package_reference/environment_variables#hfhubdisablexet)
* [`HF_XET_CACHE`](../package_reference/environment_variables#hfxetcache)
* [`HF_XET_HIGH_PERFORMANCE`](../package_reference/environment_variables#hfxethighperformance)
* [`HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY`](../package_reference/environment_variables#hfxetreconstructwritesequentially)

### HF_XET_CHUNK_CACHE_SIZE_BYTES

この変数はもはや効果を持ちません。`hf_xet`はダウンロードにローカルチャンクキャッシュを使用しなくなっており、この変数を設定してもキャッシュは有効になりません。詳細は[xet-core#715](https://github.com/huggingface/xet-core/issues/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](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi)の任意のメソッドを呼び出すと、[OfflineModeIsEnabled](/docs/huggingface_hub/v2.4.0/ja/package_reference/utilities#huggingface_hub.errors.OfflineModeIsEnabled)例外が発生します。

**注:** ファイルの最新バージョンがキャッシュされていても、`hf_hub_download` を呼び出すと、新しいバージョンが存在しないことを確認するために HTTP リクエストが送信されます。`HF_HUB_OFFLINE=1` を設定すると、この呼び出しがスキップされ、読み込み時間が短縮されます。

オフラインモードが有効かどうかを確認するには、[is_offline_mode()](/docs/huggingface_hub/v2.4.0/ja/package_reference/utilities#huggingface_hub.is_offline_mode)ヘルパーを使用できます。

### HF_HUB_DISABLE_IMPLICIT_TOKEN

Hub へのすべてのリクエストに対して認証が必須であるわけではありません。例えば、`"gpt2"` モデルの詳細をリクエストする場合は、認証は不要です。ただし、ユーザーが[ログイン](../package_reference/login)している場合、プライベートリポジトリやゲート付きリポジトリにアクセスする際のユーザー体験を向上させるため（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` を設定してください。

詳細については、[キャッシュの制限](../guides/manage-cache#limitations)を参照してください。

### 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拡張機能](../guides/cli-extensions)を実行する前に、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 が動作しない理由を理解するために、[問題を報告し、診断情報を含める](https://github.com/huggingface/xet-core?tab=readme-ov-file#issues-diagnostics--debugging)ことを検討してください。

### HF_HUB_ENABLE_HF_TRANSFER

> [!WARNING]
> これは非推奨の環境変数です。Hugging Face Hub が完全に Xet ストレージバックエンドで動作するようになったため、すべてのファイル転送は `hf-xet` バイナリパッケージを介して行われます。このパッケージはチャンクベースの重複排除戦略を用いて効率的な転送を提供し、`huggingface_hub` とシームレスに統合されています。つまり、`hf_transfer` はもはや使用できません。より高いパフォーマンスに関心がある場合は、[`HF_XET_HIGH_PERFORMANCE` セクション](#hf_xet_high_performance) をご覧ください。

### HF_HUB_DISABLE_SHARED_BLOBS

`1`に設定すると、キャッシュ全体で共有されるブロブストアが無効になります。デフォルトでは、正常にダウンロードされた Xet ファイルは `<CACHE_DIR>/blobs/<prefix>/<xet_hash>` に保存され、リポジトリのキャッシュにシンボリックリンクとして配置されるため、同一のファイルはリポジトリをまたいでディスク上に1回のみ保存され、再取得せずに再利用できます。この最適化はデフォルトで有効ですが、Xet が利用できない場合（`HF_HUB_DISABLE_XET=1` が設定されている場合など）や、ローカルでシンボリックリンクがサポートされていない場合は無効になります。そのような場合は、リポジトリローカルの通常のストレージに静かにフォールバックします。詳細は [キャッシュのガイド](../guides/manage-cache#shared-blobs-across-repos) を参照してください。

### HF_XET_HIGH_PERFORMANCE

`hf-xet`を、マシン上のネットワークおよびディスクリソースを最大限に活用するための増強設定で動作させます。ハイパフォーマンスモードを有効にすると、このマシンのネットワーク帯域幅を飽和させ、並列アップロード/ダウンロード処理にすべてのCPUコアを利用しようとします。

これは従来の`HF_HUB_ENABLE_HF_TRANSFER=1`環境変数に相当するものですが、`hf-xet`に適用されるものです。

Xetストレージと`hf_xet`の利点について詳しく知るには、この[セクション](https://huggingface.co/docs/hub/xet/index)を参照してください。

### HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

この変数はもはや使用されていません。`hf_xet` 1.3.0 以降、ファイルは常にローカルディスクにシーケンシャルに書き込まれます（[v1.3.0 のファイルライター](https://github.com/huggingface/xet-core/blob/v1.3.0/file_reconstruction/src/data_writer/data_writer.rs#L76-L91)を参照）。

## 非推奨の環境変数

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](https://no-color.org/)を参照してください。

### XDG_CACHE_HOME

`HF_HOME`が設定されていない場合のみ使用されます!

Linuxマシンにおいて、[ユーザー固有の非必須（キャッシュ）データをどこに書き込むかを設定する](https://wiki.archlinux.org/title/XDG_Base_Directory)デフォルトの方法です。

`HF_HOME`が設定されていない場合、デフォルトのホームは`"~/.cache/huggingface"`ではなく、`"$XDG_CACHE_HOME/huggingface"`になります。