No matching distribution found for paddlepaddle の直し方（Python 3.14 に wheel が無い）

新しく入れた Python で pip install paddlepaddle を実行すると、パッケージ名を打ち間違えたときと見分けの付かないエラーで止まることがあります。

ERROR: Could not find a version that satisfies the requirement paddlepaddle (from versions: none)
ERROR: No matching distribution found for paddlepaddle

パッケージ名は合っています。原因は、いま動かしている環境向けの配布ファイルが PyPI に置かれていないこと。検索でコピペする文字列は行によって変わるので、検証で実際に得たものを並べます。

• 最終行: No matching distribution found for paddlepaddle
• その直前の行: Could not find a version that satisfies the requirement paddlepaddle
• 候補が 1 件も無いことを示す括弧: (from versions: none)
• 版を指定して入れた場合は指定ごと出る: No matching distribution found for paddlepaddle==3.3.1
• pip install を使わず pip index versions paddlepaddle を叩いた場合も、最終行は同じ No matching distribution found for paddlepaddle
• pip の終了コードは 1

結論を先に書くと、直し方は paddlepaddle を動かすインタプリタを、wheel が配布されている Python に合わせるの一手です。pip 側のオプションで 3.14 に入れる道は無い。ただしシステム全体の Python を下げる必要はなく、paddle を使うプロセスだけ古い版に閉じ込めれば済みます。

# 検証した最小の形（Python 3.11 なら同じコマンドが通り、paddle 3.3.1 が入る）
docker run --rm python:3.11 sh -c 'pip install -q paddlepaddle && python -c "import paddle; print(paddle.__version__)"'

いま使っている Python に候補があるかを見る

pip index versions は、そのインタプリタ向けの配布ファイルがある版だけを並べます。一覧に出ることは、依存解決やインストールや import の成功を保証しません。同じコマンドの出力がインタプリタごとに変わるので、環境差を疑うときの最初の一手になります。

python -V
python -m pip index versions paddlepaddle

Python 3.11 では 2.6.2 まで遡って候補が並びます。

paddlepaddle (3.3.1)
Available versions: 3.3.1, 3.3.0, 3.2.2, 3.2.1, 3.2.0, 3.1.1, 3.1.0, 3.0.0, 2.6.2

Python 3.13 では、同じコマンドの一覧から 2.6.2 が落ちる（2.6.2 に 3.13 向けの配布ファイルが無いため）。

paddlepaddle (3.3.1)
Available versions: 3.3.1, 3.3.0, 3.2.2, 3.2.1, 3.2.0, 3.1.1, 3.1.0, 3.0.0

Python 3.14 では一覧が出ず、No matching distribution found for paddlepaddle で終わります。候補がゼロなので、プレリリースを許す --pre も、ソースからの導入を狙う --no-binary :all: も、同じ 2 行を返す。版を指定した pip install "paddlepaddle==3.3.1" の場合は、行末が打った指定に変わるだけで結果は同じです。

ERROR: Could not find a version that satisfies the requirement paddlepaddle==3.3.1 (from versions: none)
ERROR: No matching distribution found for paddlepaddle==3.3.1

どの Python なら入るのか

PyPI に置かれた paddlepaddle==3.3.1 の配布ファイルは、すべて wheel。ファイル名の cp39 cp310 のような Python タグが、対応するインタプリタを表します。

Python	3.3.1 の wheel（PyPI の配布ファイル）	errfix で実測したか
3.14	無い	実測: pip install が失敗（終了コード 1）
3.13	cp313 あり	未実測（pip index versions に候補が並ぶことは確認）
3.12	cp312 あり	未実測
3.11	cp311 あり	実測: install 成功、import paddle が 3.3.1
3.10	cp310 あり	未実測
3.9	cp39 あり	未実測

wheel の有無は PyPI のメタデータで確認できる事実、右列は errfix が実際にコンテナで動かした点です。3.14 が落ちること、3.11 で入ることの 2 点は実測、その間の版は「配布ファイルがあるので pip は候補として選べる」ところまでを根拠にしています。

もう 1 本の軸: OS と CPU アーキテクチャ

Python の版と並ぶもう 1 本の軸が、OS と CPU アーキテクチャです。ただし出方が違う。wheel のある Python を使っている限り、エラーにならず、入る版が黙って古いところで止まります。

以下は PyPI（pip install の既定インデックス）に置かれた配布ファイルの話です。そこでの paddlepaddle のプラットフォームタグはリリースごとに増減しており、Linux の arm64（manylinux2014_aarch64）向け wheel は 3.2.2 まで存在して 3.3.0 で消えました。Intel Mac（macosx_10_9_x86_64）向けは 3.0.0 が最後。pip は「一致する wheel のうち最も新しい版」を選ぶので、これらの環境では pip install paddlepaddle が成功したまま、最新より古い版が入ります。

次の表は Python 3.9〜3.13（wheel のある版）での結果です。 Python 3.14 では、どのプラットフォームでも候補がゼロなので、この表は当てはまりません。

環境（Python 3.9〜3.13）	一致する最も新しい wheel	pip install paddlepaddle の結果
Linux x86_64	3.3.1	3.3.1 が入る
Linux arm64	3.2.2（3.3.0 以降は wheel が無い）	3.2.2 が入る
Apple Silicon Mac	3.3.1	3.3.1 が入る
Intel Mac	3.0.0（3.1.0 以降は wheel が無い）	3.0.0 が入る

該当するマシンを持っていなくても、pip に解決だけさせれば確かめられます。

python -m pip download --no-deps --only-binary=:all: \
  --python-version 311 --platform manylinux2014_aarch64 -d /tmp/w paddlepaddle

これは paddlepaddle-3.2.2-cp311-cp311-manylinux2014_aarch64.whl を落として終了コード 0 を返します。同じコマンドの --python-version を 314 にすると、こんどは終了コード 1 で候補ゼロになる。「同じ requirements.txt なのに arm64 のランナーだけ paddle が古い」という食い違いは、この仕組みで説明が付きます。

なお、arm64 の wheel が作られなくなったわけではありません。Paddle は公式のインデックス（-i https://www.paddlepaddle.org.cn/packages/stable/cpu/）を別に持っていて、そちらには paddlepaddle-3.3.1-cp313-cp313-linux_aarch64.whl が置かれています。PyPI に上げられないタグ（manylinux ではなく素の linux_aarch64）なので、既定のインデックスからは見えないだけです。「PyPI に無い」と「存在しない」は別の主張で、cp314 の wheel はどちらのインデックスにもありません。

エラーになるのはどんな環境か

エラーになるのは、いま動いているインタプリタの互換タグに一致する wheel が 1 つも無いときです。 軸を数え上げるより、wheel が存在する組み合わせを覚えるほうが確実です。PyPI 上の paddlepaddle は、CPython の通常ビルド cp39〜cp313 × manylinux1_x86_64 / macosx_11_0_arm64 / win_amd64 しか配布していません。この外側はすべて同じ 2 行になります。

pip download で pip 自身に解かせて確認した、候補ゼロになる環境です。

環境	候補
Python 3.14（本記事の主題）	ゼロ
musl libc の Linux（Alpine 系）	ゼロ
free-threaded ビルド（python3.13t。ABI タグが cp313t）	ゼロ
Windows の ARM64（win_arm64）	ゼロ
PyPy	ゼロ

python:3.11-alpine で pip install paddlepaddle を実行すると、Python の版が対応範囲内でも終了コード 1 になります。free-threaded ビルドは python -V では通常ビルドと見分けが付かないので、python -VV（free-threading build と出る）で確かめてください。エラー文は原因の軸を教えてくれません。

なぜ (from versions: none) と出るのか

pip は PyPI からファイル一覧を取り、動いているインタプリタの互換タグに一致しないものを、版を数える前に捨てます。paddlepaddle が PyPI に上げているファイルは wheel だけで、ソース配布（sdist）は 1 つも無い。したがって 3.14 では、タグの照合を抜けたファイルがゼロになり、pip から見て「そもそも候補が存在しない」状態になります。括弧の (from versions: none) は、版の選択に失敗したのではなく、選択の対象が空だったことを表しています。

sdist があれば、pip は wheel が無いときにソースを取ってビルドへ回す。paddlepaddle にその逃げ道が無いことが、--no-binary :all: を付けても結果が変わらない理由です。

もう一点、paddlepaddle の PyPI メタデータには requires_python が設定されていません。宣言があれば pip が「この版は別の Python を要求する」と補足する余地がありますが、宣言が無いので、出るのは版に触れない 2 行だけになります。打ち間違いのときと同じ文面が出るのはこのためです。候補がある場合は括弧の中に版が並ぶ（(from versions: 2.3.2, ...) のように）ので、none かどうかが見分けの目印になります。

「昨日まで動いていたのに、新しいマシンで落ちる」理由

paddle を使うコード自体は変わっていないのに、この症状は環境を作り直した瞬間に現れます。Python の版を固定していない環境（FROM python:3 のようなベースイメージ、OS のアップグレードで入れ替わったシステム Python、brew や uv が入れた最新のインタプリタ）は、Python の新しい版がリリースされ次第、静かに 3.14 へ乗り換わるためです。paddle の側は、wheel をビルドし直すまで新しい Python に追随しない。この時間差の間だけ、同じ requirements.txt が古いマシンでは通り、作り直した環境では 1 行目の pip install で落ちるという差が出ます。

上流にも同じ報告があります。PaddleOCR の Issue #17370（python 3.14 support）は、Python 3.14 の環境で Could not find a version that satisfies the requirement paddlepaddle (from versions: none) が出ることを報告したものです。ただし読み方に注意が要ります。この issue は「これは PaddleOCR ではなく Paddle 本体の話」として PaddlePaddle/Paddle へ案内され、報告者が自分で閉じました。GitHub 上は completed（対応済み）として表示されますが、wheel の追加時期に答えた人はいません。報告者が叩いていたのも PyPI ではなく Paddle 公式のインデックスで、そちらにも 3.14 向けの配布ファイルはありません。

Paddle 本体には Python 3.14 対応のタスクをまとめた Issue #76250 があり、こちらも閉じています。それでも配布ファイルに cp314 は現れていない。上流の issue が閉じていることを、wheel が出たことの根拠にしないでください。

直し方: paddle を使うところだけ古い Python にする

システムの Python を 3.14 から入れ替える必要はありません。paddle を動かす仮想環境やコンテナだけ、wheel のある版に固定します。

コンテナで動かしているなら、ベースイメージのタグを固定するのが最小の変更です。python:3 や python:latest のような浮動タグは、新しい Python が出た時点で 3.14 を指すようになる（実際、いま python:3 は 3.14.6 です）。固定の理由は、requirements.txt ではなくタグを決めているこのファイルに書き残します。

# PyPI にも Paddle 公式インデックスにも cp314 の wheel が無いため、3.14 では pip install が通らない。
# cp314 が現れたら、このタグを上げて pip install を試す。
FROM python:3.11

# paddle 側の版も固定する。浮動させると最新の 3.3.1 が入る。
RUN pip install "paddlepaddle==3.2.2"

paddle の版まで固定するのは、インタプリタを合わせたあとに別のエラーへ進まないためです。 ここで pip install paddlepaddle と書くと、いまは 3.3.1 が入ります。PaddleOCR を CPU で推論させると、その 3.3.1 は ConvertPirAttribute2RuntimeAttribute not support で止まる版です。インストールは通ったのに推論で落ちる、という次の壁にそのまま当たります。

用途によって固定先は変わります。PaddleOCR を CPU で使うなら上の 3.2.2 が実測済みの選択肢（enable_mkldnn=False で 3.3.1 のまま回避する道もある。姉妹記事を参照）。それ以外の用途なら最新でも構いませんが、版は書いておくほうが、次に環境を作り直した人が同じ調査を繰り返さずに済みます。

ホストに複数の Python が入っているなら、paddle 用の仮想環境をその版で作ります。仮想環境の中だけが 3.11 になり、システムの 3.14 は触りません。

python3.11 -m venv .venv
.venv/bin/pip install paddlepaddle
.venv/bin/python -c "import paddle; print(paddle.__version__)"

Windows では py -3.11 -m venv .venv で作り、.venv\Scripts\python -m pip install paddlepaddle を使います（bin ではなく Scripts に置かれます）。

最後の行が版を表示すれば入っています。import paddle の際に UserWarning: No ccache found. が出ることがありますが、これは拡張のビルドに関する注意で、このエラーとは無関係です。

GPU 版を使っている場合は前提が変わる。paddlepaddle-gpu は PyPI では 2.6.2 が最新で、Python タグも cp38 から cp312 まで。3.x 系の wheel は PyPI に無く、公式のインデックス URL を指定して入れる形になるため、対応する Python の範囲もそちらの配布物を見て判断してください。PyPI 側だけを見ている限り、GPU 版は Python 3.13 でも 3.14 でも入りません。本記事で確認したのは CPU 版 paddlepaddle の PyPI 配布と、x86_64 Linux コンテナ（python:3.14 / python:3.11 / python:3.11-alpine）での挙動、および pip に解決だけさせた他プラットフォーム向けの選択結果です。

いつ再評価するか

この記事の対象は、paddle が 3.14 向けの wheel を出せば消えます。恒久的に 3.11 へ貼り付く理由は無い。再評価の目印は、自分の環境の互換タグに一致する cp314 の wheel が現れることです。

いちばん速い確認は、上げたい環境で実際に入れてみることです。

# 3.14 の環境でこれが通るようになったら、固定を外してよい
python -m pip install paddlepaddle

タグの有無を先に見たいなら python -m pip index versions paddlepaddle でも分かりますが、これは実験的なコマンドで、警告が出るうえ将来消える可能性があります。配布元が PyPI と Paddle 公式インデックスの 2 つある点にも注意が要る。arm64 の wheel がそうだったように、片方にだけ現れることがあります。

cp314 という文字列だけを見るのも足りません。wheel の適合は Python タグ・ABI タグ・プラットフォームタグの三つ組で決まるので、cp314-cp314-win_amd64 だけが出た時点で Linux のベースイメージを上げると、また落ちます。判断は、そのとき自分が動かす環境の pip にさせるのが確実です。

Python の新しい版が出た直後に同じことが繰り返される点にも注意が要ります。Issue #17370 が立った時期には「wheel は 3.12 まで」と書かれていましたが、現在の 3.3.1 には cp313 の wheel が含まれている。他人の報告に書かれた対応版はすぐ古くなります。

切り分け

• python -VV とベースイメージを先に見る: No matching distribution found は「あなたの環境向けのファイルが無い」としか言っていない。まず Python の版と種別（3.14 以上か、free-threaded ビルドか、PyPy か）を python -VV で確認し、次にベースイメージが Alpine（musl）でないか、Windows なら ARM64 でないかを見る。wheel があるのは CPython の通常ビルド cp39〜cp313 × Linux x86_64 / Apple Silicon / Windows x64 だけで、その外側はすべて同じ 2 行になる。CPU アーキテクチャだけは別の出方をすることがあり、Linux arm64 と Intel Mac ではエラーにならず古い版が入る。パッケージ名の打ち間違いと同じ文面なので、綴りも一度確認しておくとよい。
• エラーは出ないのに paddle が古い場合: Linux arm64 や Intel Mac では、一致する wheel のうち最も新しいものが選ばれる結果、pip install paddlepaddle が成功したまま 3.2.2 や 3.0.0 で止まる。CI と手元で paddle の版が食い違うなら、python -c "import paddle; print(paddle.__version__)" を両方で出して比べる。
• install は通ったのに推論で落ちる場合は別問題: pip install paddlepaddle が成功したうえで、PaddleOCR の predict() が NotImplementedError: (Unimplemented) ConvertPirAttribute2RuntimeAttribute not support で止まるなら、Python の版ではなく paddle の実行エンジン側の回帰です。そちらは ConvertPirAttribute2RuntimeAttribute not support の直し方 で扱っています。
• paddleocr を入れても paddle は入らない: paddleocr は paddlepaddle を依存に宣言していないため、pip install paddleocr は成功したまま実行エンジンだけ入っていない状態になり得る。paddle は自分で入れる前提と考える。
• import 時に libGL.so.1 で止まる場合: これは OS パッケージの不足で、Python の版とは無関係。opencv-python-headless に寄せるか、ディストリに合わせて OpenGL 関連のパッケージを入れる。