pipの候補不在エラーの対処法

冒頭まとめ

pip installで次のエラーが出た場合、pipは指定された要件を満たす配布ファイルを選べていません。

ERROR: Could not find a version that satisfies the requirement demo_probe==99.0 (from versions: 1.0)
ERROR: No matching distribution found for demo_probe==99.0

from versions: noneでも、パッケージが公開されていないとは限りません。Pythonの版やOSに合わないファイルが候補から外れた場合、取得先に接続できなかった場合にも、候補が残らないことがあります。

まず、エラーが出た環境で、使っているPythonとpipを確認してください。

python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip --version

そのうえで、最後の2行より前に出ている接続エラーや候補の除外理由を読みます。名前、版の指定、Pythonへの対応、取得先、OS向けの形式を順に確認すると、直す場所を絞れます。

エラーの意味とfrom versionsの読み方

pipは、取得先から見つけたファイルをすべてインストール候補にするわけではありません。候補選択の公式文書では、リンクから候補を作る段階で、ファイル形式やPythonへの対応などを評価すると説明しています。

pip 26.2.1の実装でも、wheelの対応条件やRequires-Pythonに合わないリンクを除外しています。wheelは、インストール用に用意された.whl形式の配布ファイルです。

そのため、from versionsはPyPIに公開された全バージョンの一覧ではありません。

pip 26.2.1の診断処理は、候補の版を集めて一覧を作り、一覧が空ならnoneを表示します。Python要件で除外した版があれば、その案内を先に出す処理もあります。Python要件の不一致が別の診断として出る場合もあり、エラーが常にこの2行になるわけではありません。

冒頭の出力は、CPython 3.12.14とpip 26.2.1で、ローカルに作成した検証用wheelを使って再現したものです。demo_probeは説明用の名前で、PyPIから取得したパッケージではありません。1.0だけがある場所で99.0を要求すると、候補一覧には1.0が出てもインストールには進めませんでした。

パッケージ名とバージョン指定を確認する

エラーに出た名前を、利用するライブラリの公式インストール手順と照合します。Pythonのimportに書く名前と、pipに渡す配布名は一致するとは限りません。PyPAの公式ガイドには、PillowをインストールしてPILを読み込む例が示されています。

標準ライブラリを、外部パッケージとしてインストールしようとしていないかも確認してください。知らない名前を別のパッケージに置き換える前に、プロジェクトが何を要求しているかを確かめます。

利用中の取得先で見つかる版は、次で確認できます。requestsは調べたい配布名に置き換えてください。

python -m pip index versions requests

このコマンドの公式文書は、Pythonやプラットフォームの条件を指定できることも説明しています。表示結果は実行環境やオプションに左右されるため、PyPIにある全配布ファイルの一覧とは区別してください。

版を==で固定している場合は、その版が存在し、対象環境で使えるかを確認します。requirements.txtや制約ファイルを使っているなら、コマンドだけでなくファイル内の指定も見直してください。

指定が誤っていた場合は、プロジェクトが対応する版へ修正します。版の指定を外すと選ばれる版が変わるため、動作確認なしに固定を外す対処は避けます。

Pythonの版とRequires-Pythonを確認する

パッケージには、使えるPythonの範囲を示すRequires-Pythonが設定されていることがあります。実行中のPythonが範囲外なら、その版は利用できません。

先ほどのsys.versionで実行環境を確認し、PyPIの対象版のページやライブラリの公式文書にある対応条件と照合してください。pip index versionsは版の一覧を見るためのコマンドで、各版のPython要件を一覧表示するものではありません。

ログには、Pythonの条件で無視された版の案内が出る場合があります。また、候補の情報を読み込んだあとで、パッケージが別のPythonを要求しているという診断が出る場合もあります。

ローカル検証では、Requires-Python: >=4を持つ検証用wheelをPython 3.12.14で指定すると、requires a different Pythonを含む診断になりました。候補が残らない場合と、候補のPython要件が満たせない場合で、表示される経路が異なります。

Pythonを変更する場合は、アプリケーション側も対応している版を選び、そのPythonの環境でインストールし直します。既存のPythonを維持する場合は、ライブラリの対応表を確認して互換性のある版を指定してください。特定の版番号を推測して選ばず、対応条件を根拠に決めます。

取得先と接続エラーを確認する

PyPIではなく、社内の取得先やローカルのファイルだけを見ている場合があります。次で設定の読み込み元と値を確認できます。

python -m pip config debug

pip configの公式文書は、debugで設定ファイルと値を表示できると説明しています。設定の優先順位では、コマンドのオプション、環境変数、設定ファイルの順に優先されます。

index-url、extra-index-url、no-index、find-linksに加え、実行したコマンドやrequirements.txt内の取得先指定も確認してください。社内パッケージは、正しい取得先と認証が必要です。公開PyPIへ切り替えれば直るとは限りません。

ログの前半に名前解決、接続の再試行、証明書検証の失敗があれば、先にその接続問題を直します。取得先から候補を受け取れていない状態で、パッケージ名や版を変えても原因が残るためです。

必要なら、詳細ログで候補を除外した理由を確認します。

python -m pip install -vvv requests

これは調査だけのコマンドではなく、条件が満たされれば実際にインストールします。変更してよい仮想環境で実行し、requestsを対象の配布名や実際の要件に置き換えてください。設定やログを共有するときは、認証情報を含むURLや社内の情報を伏せます。

OSとCPUに対応するwheelを確認する

wheelには、Pythonの実装や版、OSなどの対応条件が付いています。手元の環境がその条件に合わなければ、ファイルは候補から外れます。

ローカル検証では、Windows向けのwheelだけを置いた場所をLinuxから参照すると、ファイルが存在していてもfrom versions: noneになりました。これは、noneをパッケージ不在と断定できない例です。

実行環境が受け付ける条件は、次で確認できます。

python -m pip debug --verbose

pip debugの公式文書と、対象パッケージの配布ファイル一覧を照合してください。DockerではホストのOSではなく、コンテナ内のPythonと環境を確認します。

pipのIssue #10501には、Jetson Xavier NXでTensorFlowのインストールが止まり、CPU、OS、Pythonなどの何が合わないのかを表示してほしいという報告があります。この報告だけでは原因を確定できませんが、診断の最後の一行では不一致の種類が分からない実例です。

ソース配布があれば、対応するwheelがなくてもビルドできる場合があります。ただし、ソース配布の有無、必要なコンパイラや外部ライブラリ、対象環境への対応を確認する必要があります。

インストールの公式文書にある--only-binaryはソース配布を使わない指定です。これを付けた場合だけ失敗するなら、wheelの有無が手がかりになります。反対に、ソースからのビルドが始まったあとの失敗は、ビルドログの別のエラーとして調べてください。

近いエラーとの違い

依存関係が競合している場合は、pipの依存関係解決の公式文書にあるように、競合の説明から各パッケージの要求を確認します。

たとえば、一方がrequests==2.25.0、もう一方がrequests>=2.28.0を必須とするなら、両方を満たす版はありません。requestsの指定だけを広げても解決せず、要求元のパッケージの組み合わせや版を変更する必要があります。

一方、インストール後の読み込みで止まる場合は、PythonのModuleNotFoundErrorの記事で、実行するPythonとインストール先の違いを確認してください。

解決手順のまとめ

最初に、使っているPythonとpipを確認し、ログの前半に接続エラーや候補の除外理由がないかを読みます。from versions: noneだけで名前の誤りと決めつけないでください。

接続に問題がなければ、配布名、固定した版、Pythonの対応範囲、取得先の指定を確認します。OS向けのwheelが候補から外れている場合は、その環境を正式にサポートする配布方法を選びます。

最後に、修正した要件でインストールし、アプリケーションの動作を確認してください。候補選び、ビルド、実行時の読み込みは別の段階なので、実際に止まった段階のログに沿って対処します。

免責事項：本記事の内容は一般的な情報提供を目的としています。インストールや設定変更は、利用するPythonのバージョンとプロジェクトの依存関係を確認したうえで行ってください。