/flags/pip/pip-install-only-binary
pip install --only-binary=:all:: install wheels only, never build from source
- tool
- pip
- command
- pip install, pip download, pip wheel
- flag
- --only-binary=:all:|:none:|PKG,...
- default
- :none: (wheels are preferred, sdists are built when no wheel fits)
pip install --only-binary=:all: PKG tells pip to use wheels only. Normally, when no wheel fits your Python version and platform, pip downloads the source distribution (sdist) and builds it locally, which can take minutes and fails without a compiler. With --only-binary=:all:, that fallback is forbidden: pip installs a wheel or stops with No matching distribution found. The option is shared by pip install, pip download and pip wheel, so the examples below use pip download, which resolves the same way without changing the environment.
A package with a wheel and one without
six publishes a wheel; pycrypto 2.6.1 only has a source archive:
echo "--- six, wheels only"
pip download --disable-pip-version-check -q --no-deps --only-binary=:all: -d dl six==1.16.0
ls dl
echo "--- pycrypto (sdist only), wheels only"
pip download --disable-pip-version-check --no-deps --only-binary=:all: -d dl pycrypto==2.6.1 2>&1 | grep "^ERROR"Output
--- six, wheels only six-1.16.0-py2.py3-none-any.whl --- pycrypto (sdist only), wheels only ERROR: Could not find a version that satisfies the requirement pycrypto==2.6.1 (from versions: none) ERROR: No matching distribution found for pycrypto==2.6.1
pip finds no acceptable file for pycrypto and reports (from versions: none): the versions exist on PyPI, they are just all source archives. The error is explained in No matching distribution found.
Values
| Value | Meaning |
|---|---|
| --only-binary=:all: | No source distributions for any package |
| --only-binary=numpy,scipy | Wheels only for the listed packages |
| --only-binary=:none: | Clear an earlier setting (for example from pip.conf) |
| --no-binary=:all: | The opposite: always build from source |
| --no-binary=PKG | Build only PKG from source |
| --prefer-binary | Prefer an older wheel over a newer sdist, but allow sdists |
| PIP_ONLY_BINARY=:all: | Environment variable form |
When a package appears in both lists, the more specific one wins, so --only-binary=:all: --no-binary=mypkg means "wheels for everything except mypkg".
When to use it
- CI and Docker images where builds must not depend on compilers and system headers. A failed resolution is better than a 20-minute build that fails halfway.
- New Python versions. Right after a Python release many packages have no wheels yet;
--only-binaryshows that immediately instead of attempting a build. - Cross-platform downloads.
pip download --platform ... --python-version ...requires it (or--no-deps), because pip cannot build an sdist for a foreign platform. See pip download for offline installs. - Security. Building an sdist runs the package's build code (
setup.pyor a build backend). Wheels are only unpacked.
In configuration
# pip.conf / pip.ini
[global]
only-binary = :all:Configuration file locations and precedence are covered in pip.conf index-url.
Pitfalls
- A version pin that exists only as an sdist becomes unresolvable; relax the pin or move to a release with wheels.
- Pure Python packages without wheels (still common for old or small projects) are excluded too. Use the per-package form if you only want to protect heavy native builds.
--only-binarydoes not choose a newer version for you when an older one is pinned; the error means "no wheel for this exact requirement".
FAQ
Why does pip try to compile a package and fail?
No wheel matches your Python version and platform, so pip falls back to the source distribution and builds it, which needs a compiler and headers. --only-binary=:all: turns that silent fallback into a clear No matching distribution error; the real fix is a Python version or package release that ships a wheel for you.
What is the difference between --only-binary and --prefer-binary?
--only-binary forbids source distributions. --prefer-binary still allows them but picks an older version that has a wheel over a newer one that only has an sdist.
Can I allow source builds for one package only?
Yes. Combine both options: --only-binary=:all: --no-binary=mypkg builds only mypkg from source. Package names are comma-separated, and :none: clears an earlier setting.