pip で特定の Python パッケージバージョンをインストールする

pip は Python パッケージをインストールしますが、Python インタープリター自体をインストールしたり切り替えたりするものではありません。使用するインタープリターで特定のパッケージバージョンをインストールするには、python -m pip install PACKAGE==VERSION を実行します。Windows では py -m pip install PACKAGE==VERSION によって、登録済みの Python ランチャーの対象を選択できます。プロジェクトごとに固定する場合は、仮想環境を使用してください。

使用する Python インタープリターで特定のパッケージバージョンをインストールする

PACKAGE と VERSION を、ディストリビューション名と利用可能なバージョンに置き換えます。たとえば python -m pip install requests==2.32.3 のようにします。== 指定子はパッケージバージョンを正確に固定します。再現可能な依存関係には便利ですが、Python 3.12、3.13 などのインタープリターをインストールするコマンドではありません。先にそのインタープリターをインストールまたは選択し、そのインタープリターの pip モジュールを呼び出してください。

修飾されていない pip コマンドより python -m pip を使う方が適切です。インタープリターとパッケージマネージャーの組み合わせが明確になるためです。プロジェクトの依存関係を変更する前に、python --version と python -m pip --version で選択したインタープリターを確認してください。

分離した環境を作成または選択して確認する

python -m venv .venv で環境を作成し、使用するシェルに合ったコマンドで有効化します。有効化後、python --version はプロジェクトのインタープリターを示し、python -m pip --version は .venv 配下のパスを示すはずです。どちらかが別の場所を指す場合は、パッケージをグローバルに固定せず、正しい環境を有効化してください。

パッケージの正確なバージョンをインストールして確認する

次のオフライン用フィクスチャは小さなパッケージの wheel を作成し、新しい仮想環境に正確なバージョンをインストールして、インストール済みメタデータを表示します。通常はパッケージインデックスが wheel を提供します。インストールコマンドで重要なのは demo-package==1.0.0 の部分です。

rm -rf /tmp/pip-pin-demo
python3 -m venv /tmp/pip-pin-demo
/tmp/pip-pin-demo/bin/python /work/build_wheel.py /tmp/pip-pin-demo/wheelhouse
/tmp/pip-pin-demo/bin/python -m pip install --no-index --find-links /tmp/pip-pin-demo/wheelhouse demo-package==1.0.0
/tmp/pip-pin-demo/bin/python -m pip show demo-package | sed -n '1,3p'

テストはこれらの正確なコマンドの前にセットアップ手順を実行し、次の出力を確認します。

Looking in links: /tmp/pip-pin-demo/wheelhouse
Processing /tmp/pip-pin-demo/wheelhouse/demo_package-1.0.0-py3-none-any.whl
Installing collected packages: demo-package
Successfully installed demo-package-1.0.0
Name: demo-package
Version: 1.0.0
Summary: Local package used by the pip version-pin fixture

実際の依存関係では、python -m pip show PACKAGE で確認するか、プロジェクト内でパッケージを import します。--upgrade を指定しない限り、通常 pip はインストール済みのバージョンをそのままにします。--upgrade を追加すると推移的依存関係が変わる可能性があるため、リゾルバーの出力を確認し、続けてプロジェクトのテストを実行してください。

requirements ファイルに固定バージョンを記録する

複数の依存関係には、requirements.txt に 1 行 1 要件で記述します。たとえば requests==2.32.3 と urllib3==2.2.2 を記述し、python -m pip install -r requirements.txt でインストールします。再現可能なアプリケーション環境を表す場合は、そのファイルをコミットしてください。依存関係管理ツールが作成するロックファイルは、解決済みの推移的依存関係も記録するため、より完全な場合があります。

正確な固定、互換範囲、アップグレードを意図的に選ぶ

プロジェクトでテスト済みの特定バージョンが必要なら、正確な固定を使います。ライブラリが複数リリースの範囲と互換性を持つ場合は、package>=1.0,<2.0 のような範囲が適切です。< や > を解釈するシェルでは、python -m pip install 'package>=1.0,<2.0' のように指定子を引用符で囲みます。バージョン指定子は PyPA のパッケージング規則に従うため、見かけ上のすべてのバージョンが各プラットフォームや Python リリースで利用できるとは限りません。

利用できないバージョンや互換性のないバージョンを調べる

境界用フィクスチャは、バージョン 1.0.0 しか含まない wheelhouse から demo-package==9.9.9 を要求します。一致するディストリビューションがないため、終了ステータス 1 になります。

/tmp/pip-pin-demo/bin/python -m pip install --no-index --find-links /tmp/pip-pin-demo/wheelhouse demo-package==9.9.9

公開インデックスからのインストールも同様に失敗する場合は、まずパッケージ名とインデックスに表示されるバージョンを確認します。次にパッケージの Requires-Python メタデータとインタープリターのバージョンを確認してください。古いリリースは新しい Python インタープリターをサポートせず、新しいリリースは古いインタープリターをサポートしない場合があります。依存関係の競合は別のリゾルバー問題です。関係のない古いパッケージバージョンを無理に使わず、プロジェクトの制約を意図的に変更してください。別の Python インタープリターが本当に必要なら、OS、Python ディストリビューション、またはバージョンマネージャーでインストールし、それを元に新しい環境を作成して、そのインタープリターの python -m pip を使用します。