# インストール

開始する前に、適切なパッケージをインストールして環境を設定する必要があります。

`huggingface_hub`は**Python 3.10+**でテストされています。

## pipでインストール

`huggingface_hub`のインストールは、[仮想環境](https://docs.python.org/3/library/venv.html)内で行うことを強く推奨します。Pythonの仮想環境に慣れていない場合は、この[ガイド](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)を参照してください。仮想環境を使用すると、異なるプロジェクトの管理が容易になり、依存関係間の互換性問題を回避できます。

プロジェクトディレクトリで仮想環境を作成することから始めます:

```bash
python -m venv .venv
```

仮想環境を有効化します。LinuxおよびmacOSの場合:

```bash
source .venv/bin/activate
```

Windowsで仮想環境を有効にするには:

```bash
.venv/Scripts/activate
```

これで、`huggingface_hub` を [PyPi レジストリから](https://pypi.org/project/huggingface-hub/) インストールする準備が整いました:

```bash
pip install --upgrade huggingface_hub
```

完了後、[インストールの確認](#check-installation)が正しく動作することを確認してください。

### オプションの依存関係をインストールする

`huggingface_hub` の一部の依存関係は、`huggingface_hub` のコア機能の実行には不要であるため、[オプション](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies)です。ただし、オプションの依存関係がインストールされていない場合、`huggingface_hub` の一部の機能が利用できない可能性があります。

オプションの依存関係は`pip`でインストールできます:
```bash
# Install dependencies for both torch-specific and MCP-specific features.
pip install 'huggingface_hub[mcp,torch]'
```

`huggingface_hub`の任意の依存関係のリストは以下の通りです:
- `fastai`、`torch`: フレームワーク固有の機能を実行するための依存関係。
- `dev`: ライブラリへの貢献に必要な依存関係。テストの実行には`testing`、型チェッカーの実行には`typing`、リンターの実行には`quality`が含まれます。

### ソースからインストール

一部のケースでは、`huggingface_hub`をソースから直接インストールすることが有用です。これにより、最新の安定版ではなく、最先端の`main`バージョンを使用できます。`main`バージョンは、最新の開発動向を把握するために役立ちます。例えば、直前の公式リリース以降にバグが修正されたが、まだ新しいリリースが公開されていないような場合に便利です。

ただし、これは`main`バージョンが常に安定しているとは限らないことを意味します。私たちは`main`バージョンの動作を維持するよう努めており、ほとんどの問題は数時間から1日以内に解決されます。問題が発生した場合は、Issueを作成してください。そうすることで、より迅速に修正できます。

```bash
pip install git+https://github.com/huggingface/huggingface_hub
```

ソースからインストールする場合、特定のブランチを指定することもできます。まだマージされていない新しい機能やバグ修正をテストしたい場合に便利です。

```bash
pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch
```

完了後、[インストールの確認](#check-installation)が正しく動作することを確認してください。

### 編集可能なインストール

ソースからのインストールにより、[editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs)を設定できます。これは、`huggingface_hub`への貢献を予定しており、コードの変更をテストする必要がある場合に有用な、より高度なインストール方法です。このためには、`huggingface_hub`のローカルコピーをマシンにクローンする必要があります。

```bash
# First, clone repo locally
git clone https://github.com/huggingface/huggingface_hub.git

# Then, install with -e flag
cd huggingface_hub
pip install -e .
```

これらのコマンドは、リポジトリをクローンしたフォルダと、Pythonのライブラリパスをリンクします。これにより、Pythonは通常のライブラリパスに加えて、クローンしたフォルダ内も参照するようになります。例えば、Pythonのパッケージが通常`./.venv/lib/python3.13/site-packages/`にインストールされている場合、Pythonはクローンした`./huggingface_hub/`フォルダ内も検索対象に含めます。

## Hugging Face CLIをインストールする 

Python環境を変更せずに`hf` CLIを設定するには、ワンライナーインストーラーを使用してください:

macOSおよびLinuxでは:

```bash
curl -LsSf https://hf.co/cli/install.sh | bash
```

Windowsの場合:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
```

既存のインストールをアップグレードするには、`hf update` を実行してください。これにより、`hf` がどのようにインストールされたか（スタンドアロンインストーラー、Homebrew、または pip）が検出され、それに該当するコマンドが実行されます。

## condaでインストール

ご使用になれている場合は、[conda-forge チャンネル](https://anaconda.org/conda-forge/huggingface_hub)を使用して`huggingface_hub`をインストールできます。

```bash
conda install -c conda-forge huggingface_hub
```

完了後、[インストールの確認](#check-installation)が正しく動作することを確認してください。

## インストールの確認

インストールが完了したら、`huggingface_hub`が正しく動作することを確認するために、以下のコマンドを実行してください。

```bash
python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"
```

このコマンドは、[gpt2](https://huggingface.co/gpt2) モデルに関する情報を Hub から取得します。出力は次のようになります。

```text
Model Name: gpt2
Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space']
Task: text-generation
```

## Windowsの制限

良い機械学習をどこでも民主化するという目標のもと、`huggingface_hub`はクロスプラットフォームのライブラリとして構築され、特にUnixベースのシステムとWindowsの両方で正しく動作するように設計されています。ただし、Windows上で実行する際に`huggingface_hub`にはいくつかの制限があります。既知の問題の包括的なリストを以下に示します。文書化されていない問題に遭遇した場合は、[Githubでissueを作成する](https://github.com/huggingface/huggingface_hub/issues/new/choose)ことでお知らせください。

- `huggingface_hub`のキャッシュシステムは、ダウンロードされたファイルを効率的にキャッシュするためにシンボリックリンクに依存しています
Hub から。Windows では、シンボリックリンクを有効にするために、開発者モードを有効にするか、スクリプトを管理者として実行する必要があります。有効化されていない場合、キャッシュシステムは動作しますが、最適化されていない方法で動作します。詳細については、[キャッシュの制限](./guides/manage-cache#limitations)セクションを参照してください。
- Hub上のファイルパスには特殊文字（例: `"path/to?/my/file"`）が含まれる場合があります。Windowsでは
[特殊文字](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names)に対してより厳格な制限を設けており、これにより Windows 上でこれらのファイルをダウンロードすることができません。おそらく稀なケースだと思います。誤りだと思われる場合はリポジトリの所有者に、あるいは解決策を模索したい場合は当方にご連絡ください。

## 次のステップ

`huggingface_hub`が正しくインストールされたら、[環境変数を設定](package_reference/environment_variables)するか、[ガイドのいずれかを確認](guides/overview)して始めることをお勧めします。

