Fixing "No matching distribution found for paddlepaddle" (no wheel for Python 3.14)

Running pip install paddlepaddle on a freshly installed Python can stop with an error that looks exactly like a mistyped package name.

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

The package name is right. The cause is that PyPI holds no distribution file for the environment you are running. The string people paste into a search box varies by line, so here are the ones the verification run actually produced.

• Last line: No matching distribution found for paddlepaddle
• The line before it: Could not find a version that satisfies the requirement paddlepaddle
• The parenthesis that says there were no candidates at all: (from versions: none)
• Pinning a version puts the pin in the message: No matching distribution found for paddlepaddle==3.3.1
• Running pip index versions paddlepaddle instead of pip install ends with the same last line: No matching distribution found for paddlepaddle
• pip exits with code 1

The conclusion first: the fix is to match the interpreter that runs paddlepaddle to a Python the wheels are published for. There is no pip option that gets it onto 3.14. You do not have to downgrade the system-wide Python, though — it is enough to confine the process that uses paddle to an older version.

# The smallest form that was verified (the same command works on Python 3.11 and installs paddle 3.3.1)
docker run --rm python:3.11 sh -c 'pip install -q paddlepaddle && python -c "import paddle; print(paddle.__version__)"'

Check whether your Python has any candidates

pip index versions lists only the versions that have a distribution file for that interpreter. Appearing in the list does not guarantee that dependency resolution, installation, or import will succeed. The output of the same command changes from interpreter to interpreter, which makes it the first thing to run when you suspect an environment difference.

python -V
python -m pip index versions paddlepaddle

On Python 3.11 the candidates go back to 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

On Python 3.13 the same command drops 2.6.2 from the list (2.6.2 has no distribution file for 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

On Python 3.14 no list appears and it ends at No matching distribution found for paddlepaddle. Since there are zero candidates, --pre (which allows pre-releases) and --no-binary :all: (which aims at building from source) both return the same two lines. Pinning with pip install "paddlepaddle==3.3.1" only changes the end of the line to the pin you typed; the result is the same.

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

Which Python does install

Every distribution file for paddlepaddle==3.3.1 on PyPI is a wheel. The Python tag in the file name — cp39, cp310 and so on — names the interpreter it goes with.

Python	3.3.1 wheel (distribution file on PyPI)	Measured by errfix?
3.14	none	measured: pip install fails (exit code 1)
3.13	cp313 present	not measured (confirmed only that candidates appear in pip index versions)
3.12	cp312 present	not measured
3.11	cp311 present	measured: install succeeds, import paddle reports 3.3.1
3.10	cp310 present	not measured
3.9	cp39 present	not measured

Whether a wheel exists is a fact you can check in PyPI’s metadata; the right-hand column is what errfix actually ran in a container. That 3.14 fails and that 3.11 installs are the two measured points; for the versions in between, the basis is only that a distribution file exists, so pip can pick it as a candidate.

The other axis: OS and CPU architecture

Alongside the Python version there is a second axis: the OS and the CPU architecture. It surfaces differently, though. As long as you are on a Python that has wheels, there is no error — the version that installs quietly stops at an older one.

What follows is about the distribution files on PyPI, the default index for pip install. The platform tags paddlepaddle publishes there have grown and shrunk from release to release: the Linux arm64 wheel (manylinux2014_aarch64) existed up to 3.2.2 and disappeared in 3.3.0. For Intel Macs (macosx_10_9_x86_64), 3.0.0 was the last. pip picks the newest version among the wheels that match, so in these environments pip install paddlepaddle succeeds and installs something older than the latest.

The table below is for Python 3.9 through 3.13 — the versions that have wheels. On Python 3.14 there are zero candidates on every platform, so it does not apply.

Environment (Python 3.9–3.13)	Newest matching wheel	Result of pip install paddlepaddle
Linux x86_64	3.3.1	installs 3.3.1
Linux arm64	3.2.2 (no wheel from 3.3.0 on)	installs 3.2.2
Apple Silicon Mac	3.3.1	installs 3.3.1
Intel Mac	3.0.0 (no wheel from 3.1.0 on)	installs 3.0.0

You can confirm this without owning the machine, by letting pip do only the resolution.

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

That downloads paddlepaddle-3.2.2-cp311-cp311-manylinux2014_aarch64.whl and exits 0. Change --python-version to 314 in the same command and it exits 1 with zero candidates. “The same requirements.txt, yet paddle is older on the arm64 runner” is explained by this mechanism.

Note that arm64 wheels have not stopped being built. Paddle keeps a separate official index (-i https://www.paddlepaddle.org.cn/packages/stable/cpu/), and paddlepaddle-3.3.1-cp313-cp313-linux_aarch64.whl is there. It carries a tag that cannot be uploaded to PyPI (plain linux_aarch64 rather than manylinux), so it is simply invisible from the default index. “Not on PyPI” and “does not exist” are different claims — and a cp314 wheel is on neither index.

Which environments produce the error

The error appears when no wheel at all matches the compatibility tags of the interpreter you are running. Rather than enumerating the axes, it is safer to remember the combinations that do have wheels. On PyPI, paddlepaddle publishes only the standard CPython builds cp39 through cp313, combined with manylinux1_x86_64 / macosx_11_0_arm64 / win_amd64. Everything outside that produces the same two lines.

These are the environments that come back with zero candidates, confirmed by having pip itself resolve them with pip download.

Environment	Candidates
Python 3.14 (the subject of this article)	zero
Linux on musl libc (Alpine and friends)	zero
free-threaded builds (python3.13t, ABI tag cp313t)	zero
Windows on ARM64 (win_arm64)	zero
PyPy	zero

Run pip install paddlepaddle on python:3.11-alpine and it exits 1 even though the Python version is inside the supported range. A free-threaded build is indistinguishable from a standard one in python -V, so check with python -VV, which says free-threading build. The error text does not tell you which axis is responsible.

Why it says (from versions: none)

pip fetches the file list from PyPI and discards everything that does not match the running interpreter’s compatibility tags, before it counts any versions. The files paddlepaddle uploads to PyPI are wheels only; there is not a single source distribution (sdist). So on 3.14 the number of files that survive tag matching is zero, and from pip’s point of view no candidate exists at all. The (from versions: none) in parentheses says that version selection had nothing to choose from, not that it failed.

With an sdist, pip would fetch the source and build it when no wheel matched. That paddlepaddle has no such escape route is why --no-binary :all: changes nothing.

One more thing: paddlepaddle’s PyPI metadata does not set requires_python. With that declaration, pip would have room to add “this version requires a different Python”; without it, all you get are the two lines that never mention a version. That is why the message is identical to the one for a typo. When candidates do exist, the parenthesis lists versions instead ((from versions: 2.3.2, ...)), so whether it says none is the thing to look at.

Why it worked yesterday and fails on a new machine

The code that uses paddle has not changed, yet this symptom appears the moment an environment is rebuilt. Environments that do not pin the Python version — a base image like FROM python:3, a system Python swapped out by an OS upgrade, an interpreter installed by brew or uv — move quietly to 3.14 as soon as a new Python is released. Paddle, on its side, does not follow a new Python until it rebuilds its wheels. In the gap between the two, the same requirements.txt passes on the old machine and fails on the rebuilt one at the very first pip install.

Upstream has the same report. PaddleOCR issue #17370 (python 3.14 support) reports Could not find a version that satisfies the requirement paddlepaddle (from versions: none) on a Python 3.14 environment. It needs care in the reading, though. The issue was redirected to PaddlePaddle/Paddle as “this belongs to Paddle itself, not PaddleOCR”, and the reporter closed it themselves. GitHub shows it as completed, but nobody answered when a wheel would be added. What the reporter was hitting was Paddle’s official index rather than PyPI — and there is no 3.14 distribution file there either.

Paddle itself has issue #76250 collecting the Python 3.14 support tasks, and that one is closed too. Even so, no cp314 has appeared among the distribution files. Do not treat a closed upstream issue as evidence that a wheel shipped.

The fix: put only the part that uses paddle on an older Python

You do not need to replace the system Python 3.14. Pin only the virtual environment or container that runs paddle to a version that has wheels.

If you run it in a container, pinning the base image tag is the smallest change. Floating tags such as python:3 or python:latest start pointing at 3.14 the moment a new Python ships (as it happens, python:3 is 3.14.6 right now). Leave the reason for the pin in the file that decides the tag — this one, not requirements.txt.

# Neither PyPI nor Paddle's official index has a cp314 wheel, so pip install cannot
# work on 3.14. When cp314 appears, raise this tag and try pip install again.
FROM python:3.11

# Pin paddle's version too. Left floating, it installs the latest 3.3.1.
RUN pip install "paddlepaddle==3.2.2"

Pinning paddle’s version as well is what keeps you from walking into the next error after fixing the interpreter. Writing pip install paddlepaddle here installs 3.3.1 today. Run PaddleOCR inference on CPU and that 3.3.1 is the version that stops at ConvertPirAttribute2RuntimeAttribute not support — installation succeeds, and you hit the next wall at inference.

What you pin to depends on the use. For PaddleOCR on CPU, the 3.2.2 above is the measured option (staying on 3.3.1 and avoiding it with enable_mkldnn=False is the other road — see the companion article). For anything else the latest is fine, but writing the version down saves whoever rebuilds the environment next from repeating this investigation.

If the host has several Pythons, create the virtual environment for paddle with that version. Only the inside of the environment is 3.11; the system’s 3.14 is untouched.

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

On Windows, create it with py -3.11 -m venv .venv and use .venv\Scripts\python -m pip install paddlepaddle (the executables land in Scripts, not bin).

If the last line prints a version, it is installed. import paddle sometimes emits UserWarning: No ccache found.; that is a note about building extensions and has nothing to do with this error.

The premise changes if you use the GPU build. On PyPI the newest paddlepaddle-gpu is 2.6.2, with Python tags from cp38 to cp312. The 3.x wheels are not on PyPI and are installed by pointing at the official index URL, so judge the supported Python range from those distribution files. Looking only at PyPI, the GPU build installs on neither Python 3.13 nor 3.14. What this article checked is the PyPI distribution of the CPU paddlepaddle, its behaviour in x86_64 Linux containers (python:3.14 / python:3.11 / python:3.11-alpine), and the selection pip makes for other platforms when asked to resolve only.

When to re-evaluate

This article’s subject disappears once paddle publishes wheels for 3.14. There is no reason to stay glued to 3.11 forever. The marker for re-evaluation is a cp314 wheel appearing that matches your environment’s compatibility tags.

The fastest check is to actually install it in the environment you want to move to.

# Once this works on a 3.14 environment, the pin can come off
python -m pip install paddlepaddle

If you would rather look at the tags first, python -m pip index versions paddlepaddle shows them — but it is an experimental command, it prints a warning, and it may disappear. Note also that there are two publishers, PyPI and Paddle’s official index. As the arm64 wheels showed, something can appear on only one of them.

Seeing the string cp314 is not enough either. Wheel compatibility is decided by the triple of Python tag, ABI tag and platform tag, so raising a Linux base image the moment cp314-cp314-win_amd64 shows up will fail again. The reliable judge is the pip in the environment you are actually going to run.

One more thing to watch: the same story repeats right after every new Python release. When issue #17370 was filed, “wheels up to 3.12” was what it said; the current 3.3.1 includes a cp313 wheel. The supported versions written in somebody else’s report go stale quickly.

Narrowing it down

• Look at python -VV and the base image first: No matching distribution found says only “there is no file for your environment”. Start with the Python version and kind (3.14 or later? a free-threaded build? PyPy?) via python -VV, then check whether the base image is Alpine (musl), or Windows on ARM64. Wheels exist only for standard CPython builds cp39–cp313 combined with Linux x86_64 / Apple Silicon / Windows x64; everything outside gives the same two lines. The CPU architecture is the one axis that can surface differently: on Linux arm64 and Intel Macs there is no error and an older version installs. And since the message is identical to a mistyped package name, it is worth checking the spelling once.
• When there is no error but paddle is old: on Linux arm64 and Intel Macs, picking the newest matching wheel leaves pip install paddlepaddle succeeding while stopping at 3.2.2 or 3.0.0. If paddle’s version differs between CI and your machine, print python -c "import paddle; print(paddle.__version__)" on both and compare.
• If installation succeeds but inference fails, that is a different problem: if pip install paddlepaddle went through and PaddleOCR’s predict() stops at NotImplementedError: (Unimplemented) ConvertPirAttribute2RuntimeAttribute not support, that is a regression in paddle’s execution engine, not the Python version. It is covered in Fixing “ConvertPirAttribute2RuntimeAttribute not support”.
• Installing paddleocr does not install paddle: paddleocr does not declare paddlepaddle as a dependency, so pip install paddleocr can succeed while leaving you without an execution engine. Assume you install paddle yourself.
• If it stops at libGL.so.1 on import: that is a missing OS package and has nothing to do with the Python version. Move to opencv-python-headless, or install the OpenGL packages your distribution names.