Python パッケージ .whl ファイルをインストールする方法

Python の .whl ファイルをインストールするには、使用する Python インタープリターとプラットフォームに合ったホイールを選び、ターミナルで python -m pip install "/path/to/package.whl" を実行します。パッケージは、その python コマンドに対応する環境にインストールされます。ホイールはインストール用に用意されたパッケージ配布形式なので、通常は自分で展開せず、pip を使ってインストールします。

.whl ファイルとは

ホイールは、Python パッケージ用のビルド済み配布形式です。インストールツールが扱える構成で、パッケージのファイルとメタデータを含む ZIP 形式のアーカイブです。ホイールには Python コード、コンパイル済み拡張機能、またはその両方が含まれることがあります。互換性のあるホイールを使えば、通常、手元のマシンでパッケージをソースからビルドする必要はありません。

ファイル名では、配布物、バージョン、互換性タグを示す部分の後に .whl 拡張子が付きます。タグは、Python の実装とバージョン、アプリケーション・バイナリー・インターフェイス（ABI）、オペレーティングシステムやプロセッサーのプラットフォームなどを示します。py3-none-any と記されたホイールは、一般にプラットフォーム固有のバイナリーを含まず、Python 3 向けです。それ以外のホイールは、特定の Python ビルドやシステムに限られる場合があります。

互換性のあるホイールを選ぶ

パッケージの配布元、または信頼できるパッケージインデックスからファイルを入手します。ダウンロードする前にパッケージのインストール手順を確認し、インストール先で使う Python インタープリターとマシンにタグが合うホイールを選びます。パッケージ名が正しくても、別のオペレーティングシステム、プロセッサーアーキテクチャ、または Python ABI 向けにビルドされたファイルは使えないことがあります。

コマンドがどのインタープリターを指すか確認するには、python --version と python -m pip --version を実行します。Python 3 のコマンドが python3 のシステムでは、一貫して python3 を使ってください。Python を複数インストールしている場合や仮想環境を使う場合は、目的の環境を先に有効化するか、その環境のインタープリターのパスを直接指定します。これにより、ある環境にインストールしたパッケージを別の環境からインポートしようとする事態を避けられます。

ローカルのホイールは、インストール先のマシンでインターネットに接続できない場合や、接続が制限されている場合に便利です。インターネットに接続できるマシンでホイールと必要な依存パッケージのホイールをダウンロードし、インストール先に転送して、ローカルのファイルからインストールします。--no-index と --find-links オプションを使うと、pip に依存パッケージをローカルディレクトリから探させることができます。ただし、不足している依存パッケージが自動的に用意されるわけではありません。

pip で .whl ファイルをインストールする

python -m pip を使うと、python が指定するインタープリター上で pip を実行できます。次の例のパスを、ホイールの場所とファイル名に置き換えてください。

from pathlib import Path
import csv
import hashlib
import subprocess
import sys
import tempfile
import zipfile

with tempfile.TemporaryDirectory() as directory:
    root = Path(directory)
    wheel = root / "sample_wheel_demo-1.0-py3-none-any.whl"
    dist_info = "sample_wheel_demo-1.0.dist-info"

    files = {
        "sample_wheel_demo.py": "message = 'wheel installed'\n",
        f"{dist_info}/METADATA": (
            "Metadata-Version: 2.1\n"
            "Name: sample-wheel-demo\n"
            "Version: 1.0\n\n"
        ),
        f"{dist_info}/WHEEL": (
            "Wheel-Version: 1.0\n"
            "Generator: example\n"
            "Root-Is-Purelib: true\n"
            "Tag: py3-none-any\n"
        ),
    }
    record_path = f"{dist_info}/RECORD"
    with zipfile.ZipFile(wheel, "w") as archive:
        for name, contents in files.items():
            archive.writestr(name, contents)
        rows = []
        for name, contents in files.items():
            digest = hashlib.sha256(contents.encode()).digest()
            import base64
            encoded = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
            rows.append((name, f"sha256={encoded}", str(len(contents.encode()))))
        rows.append((record_path, "", ""))
        import io
        record = io.StringIO()
        csv.writer(record, lineterminator="\n").writerows(rows)
        archive.writestr(record_path, record.getvalue())

    target = root / "installed"
    result = subprocess.run(
        [sys.executable, "-m", "pip", "install", "--no-index", "--no-deps",
         "--target", str(target), str(wheel)],
        capture_output=True, text=True,
    )
    if result.returncode == 0:
        print("Installed sample-wheel-demo 1.0")
    else:
        print("Installation failed:", result.stderr.strip())
        raise SystemExit(result.returncode)

この単体で実行できる例では、一時ディレクトリに小さなホイールを作成し、現在のインタープリターの pip で別のターゲットディレクトリにインストールします。手元にあるホイールには、python -m pip install "/path/to/package.whl" の形式を使います。パスを引用符で囲むと、ディレクトリ名やファイル名に空白が含まれていても扱えます。Windows では、"C:\Users\Ada\Downloads\package.whl" のようなパスを指定します。PowerShell とコマンドプロンプトのどちらでも、同じように引数を引用符で囲めます。この例が表示するメッセージは英語のままです。

オフラインで使うホイールと依存パッケージをダウンロード済みなら、次のように pip にそのディレクトリを指定します: python -m pip install --no-index --find-links "/path/to/wheels" "/path/to/package.whl"。ローカルに依存パッケージのファイルがなければ、pip はオフライン中にそれらを取得できません。

インストールエラーのトラブルシューティング

• 一致する配布物がない、またはホイールのタグが未対応: ホイールの Python、ABI、プラットフォームのタグが、使用するインタープリターとマシンに合っているか確認します。配布元から一致するビルドを入手するか、配布元が案内する別の対応済みインストール方法に従ってください。
• 依存パッケージが見つからない: pip のエラーメッセージを読み、どの依存パッケージが必要か確認します。互換性のある依存パッケージのホイールもインストールするか、インターネットに接続できる場合は、設定済みのパッケージインデックスから pip に解決させます。オフラインでインストールする場合は、必要な依存パッケージのホイールをすべてローカルディレクトリに含めてください。
• インストールはできたがインポートできない: python -m pip --version の結果と、アプリケーションの実行に使っているインタープリターを確認します。同じインタープリターで両方を実行するか、インストール前に正しい仮想環境を有効化してください。
• アクセスが拒否される: 自分が所有する仮想環境を使う方法を優先してください。システムのインタープリターでは python -m pip install --user ... によるユーザー単位のインストールが適する場合もありますが、管理対象の環境では無効になっていることがあります。その場合は、環境の管理者の指示に従ってください。
• pip コマンドが見つからない: python -m pip または python3 -m pip を実行します。pip が利用できないというエラーが出る場合は、そのインタープリターについて Python の配布元が案内する pip のセットアップ手順に従ってください。
• Git リポジトリにホイールがある: リポジトリをクローンすると、追跡対象のファイルがダウンロードされるだけです。パッケージがインストールされるわけではなく、互換性のあるホイールが含まれているとも限りません。プロジェクトのメンテナーの指示を確認し、公開済みのホイールファイルを探して、ローカルファイルを pip でインストールしてください。リポジトリのコードやダウンロードした成果物は、提供元の信頼性と検証方法を考慮して扱います。

問題が起きた場合は、pip のメッセージ全体を読み、原因が選択したホイール、依存パッケージ、Python 環境、または権限のどれにあるかを特定します。原因に対処してから、目的のインタープリターでインストールをやり直してください。