piwheels

You should have a file at /etc/pip.conf containing:

[global]
extra-index-url=https://www.piwheels.org/simple

If that's there, pip should use piwheels. If not, create the file and add those lines to it.

Note that pip version 9 or above is required.

You can use piwheels as an additional index, which will allow pip to fall back to PyPI if the requested package (or one of its dependencies) is not available on piwheels, by using the --extra-index-url option, for example:

pip3 install numpy --extra-index-url https://www.piwheels.org/simple

Alternatively, to only use piwheels, use the -i or --index-url option, for example:

pip3 install numpy -i https://www.piwheels.org/simple

or

pip3 install numpy --index-url https://www.piwheels.org/simple

If your pip is configured to use piwheels, but you want to use PyPI instead, you can either remove or comment out the extra-index-url configuration in /etc/pip.conf, or you can explicitly request no binary distribution in the installation command, and you'll get source distribution from PyPI, for example:

pip3 install numpy --no-binary :all:

or to use the --no-binary option for a single package (e.g. get the tensorflow wheel but force a build of one of its dependencies, grpcio):

pip3 install tensorflow --no-binary grpcio

Since the release of Debian Bookworm, installations with sudo are no longer permitted. Instead, it is recommended to use a virtual environment.

Once a virtual environment is activated, either pip or pip3 can be used, as they both refer to the virtual environment's Python.

See the section on virtual environments.

To create a virtual environment:

$ sudo apt install virtualenv python3-virtualenv -y
$ virtualenv -p /usr/bin/python3 testpip

Enable it:

$ source testpip/bin/activate

Now you can use pip or pip3 to install packages into your environment:

(testpip) $ pip3 install numpy

You can either specify the version you want:

pip3 install numpy==1.18.0

Or you can use the --prefer-binary flag:

pip3 install numpy --prefer-binary

This will install the latest version that's available as a wheel.

Time saved depends on the package requested, and the Raspberry Pi model used. Some packages usually require significant build time, which is avoided by using piwheels. Many packages are usually quite quick to install anyway, and only a small amount of time is saved. Build time on Pi 1 and Pi Zero is much longer than Pi 3 (roughly 6x), so the biggest gains are there.

piwheels saved Raspberry Pi users over 128 years in 2019 and 269 years in 2020. See more details in the stats blog posts.

You don't need to do anything. All package releases on PyPI are automatically processed by the piwheels project. As long as you upload a source distribution, we'll attempt to build it.

Some packages fail to build, for various reasons. If you would like to investigate, try building the package yourself on a Raspberry Pi 3 or 4 with a Lite image by running pip3 wheel package==version --no-deps --no-binary package.

Please see the questions on

You may discover that piwheels manages to build some versions of a package and fails to build others. Success and failure per ABI is noted on each package's project page. Search for a package on the package list page. If you maintain the package or otherwise have a solution for the build, please let us know and we'll try to resolve it. See the questions on reporting package issues and missing packages.

piwheels should notice the registration of a new package or version within about 10 seconds. How long it takes for that version to be built then depends on two factors:

• Build queue. Sometimes, particularly when a new Debian version is released, piwheels will be busy working through a large build queue, and it may take a while to reach a package.
• Build time. If the package is pure python it should build within a few seconds and appear very quickly. Alternatively if it's a big chunk of C++ with lots of generics it can take hours to compile (the longest compile time for a successful build is currently over 3 hours).

So ultimately the time for a new release to appear can be anything from about 10 seconds up to several hours (for complex to build packages) or several days (when piwheels has a large backlog of packages to work through).

No. All wheels are built natively on the Raspberry Pi OS on Raspberry Pi 3 and 4 hardware.

All current Raspberry Pi models (as of October 2023) are supported:

• Raspberry Pi 5
• Raspberry Pi 400
• Raspberry Pi 4
• Raspberry Pi 3
• Raspberry Pi 2
• Raspberry Pi 1
• Raspberry Pi Zero
• Raspberry Pi Zero 2

Please also observe answers to questions relating to operating systems and Python versions.

Some packages build differently depending on the tools available. For example, if the package matplotlib is built with pyqt installed, the wheel will depend on the user also having pyqt installed. If it is built without pyqt, the user can use matplotlib without pyqt.

If you find an issue with a package installed from piwheels, please let us know and we'll try to resolve it. See the questions on reporting package issues and missing packages.

piwheels supports Python 3 only. While most packages available will work in any version of Python 3, some packages are only compatible with the minor version with which they were built. We build using for the ABI of the Python 3 version distributed with Debian releases. We stop building on each Debian version as it goes end-of-life:

• Jessie - Python 3.4 (end-of-life)
• Stretch - Python 3.5 (end-of-life)
• Buster - Python 3.7 (end-of-life)
• Bullseye - Python 3.9
• Bookworm - Python 3.11

The source code for the piwheels project can be found on GitHub at github.com/piwheels/piwheels.

The piwheels project is hosted on a cluster of Raspberry Pi 3 and 4s provided by Mythic Beasts. The web pages and wheel files are served from a single Raspberry Pi 4, we use a separate VM to host the postgreSQL database, and use several other Raspberry Pis across different OS versions to build wheels.

The original build run was completed by a total of 20 Raspberry Pis, and now a smaller cluster remains active, continuing to build new package releases.

First of all: check your pip configuration and confirm that piwheels is in fact being used. You should see Looking in indexes: https://pypi.org/simple, https://www.piwheels.org/simple.

If you are definitely using piwheels, it could be that while the package you installed was available on piwheels, perhaps one of its dependencies is not available, and requires downloading from PyPI and building from source. Reading the output from the pip command should tell you what's going on, particularly when the -v flag is used.

While the hardware in Raspberry Pi 1 and Zero is Armv6, Pi 2 is Armv7, Pi 3, 4, 400 and Zero 2 are Armv8, the (32-bit) operating system images provided on raspberrypi.com are made to support all three architectures (and are compatible with all Raspberry Pi products to date) by operating in Armv6 userland.

However, wheels built on a Raspberry Pi 2/3/4 running the 32-bit OS are tagged armv7l. Since wheels built on a Raspberry Pi 3/4 will work on a Pi 5, 4, 3, 2, 1, Zero or Zero 2, we simply provide Pi 3/4-built wheels renamed armv6l, with a few exceptions (some packages, like opencv and tensorflow, are built with optimisations available on Pi 3/4).

Also see the following question.

The repository at piwheels.org does not currently support the 64-bit version of the Raspberry Pi OS. We have plans to support it in future, but this requires a significant amount of work, and then rebuilding all wheels on the new architecture. Read more on the blog and issue #220.

The repository at piwheels.org does not support Ubuntu or other distributions. It's possible some wheels will work on other distributions, but we can't promise that they will. Wheels are built against certain shared libraries which we know are available to Raspberry Pi OS users too.

It would be possible for someone to run their own instance of piwheels to build wheels on and for another distribution, like Ubuntu. To those interested in doing this, please see the docs, and feel free to get in touch.

Some wheels may work on other Arm platforms, but we can't guarantee this. We only officially support Raspberry Pi OS on Raspberry Pi, but you may have success using wheels on other Debian-based distributions or other boards. We won't accept bug reports for unsupported platforms.

See the following question.

Pure Python wheels will likely work, but there's a much smaller speed increase installing from wheels over source distribution. Packages requiring compilation are built for a specific architecture, so they will not be useful on non-Arm platforms and will be ignored. Assuming your pip configuration is set to fall back to PyPI, installation will continue from there, which may involve building from source. There's no harm in trying to use piwheels on a PC/Mac but it's not likely to be very useful.

No — we can't. Only package maintainers can upload files to PyPI. We don't recommend that package maintainers upload Raspberry Pi Arm wheels to PyPI in case they don't work on other Arm platforms. Raspberry Pi users have access to piwheels, so that should suffice.

PyPI now allows uploading Armv6 and Armv7 wheels, but we recommend that you don't upload Arm wheels to PyPI for incompatibility reasons and other complications.

Wheels built on a Raspberry Pi 3, although tagged armv7l are not truly Armv7, and may be incompatible with other Arm platforms. If your package is made exclusively for the Raspberry Pi platform, there is no harm in uploading Arm wheels to PyPI, and this will speed up the installation for users who do not have pip configured to use piwheels. However, it is not possible to upload two identical wheel files with armv6l and armv7l platform tags, so the second one will be rejected by PyPI.

If you intend for your package to be installed by users in multiple Arm platforms, you may be best not to upload Arm wheels to PyPI and instead leave Raspberry Pi users to get a wheel from piwheels, and leave other Arm platform users to build from source.

Please contact us by email or open an issue on our package issue tracker on GitHub (see the question on package issues) and we'll endeavour to remove it as soon as we can. In cases where it's not obvious that the requester owns the package to be removed, we may require further evidence that you are authorized to request its removal (e.g. posting as the GitHub owner of the project, or some similar standard of proof on the relevant hosting service).

If you do request removal, please let us know if you'd like piwheels to avoid building future releases of your package. We can arrange this trivially with a skip flag in our database.

We only log downloads from piwheels.org, not from PyPI. If your package is pure Python, and you submit wheels to PyPI, users may get the file from PyPI, not from piwheels. You can use projects like pypistats.org to get the numbers from PyPI, and aggregate them.

Additionally, if your project is packaged for Debian, people could be installing your package with apt, rather than pip.

Packages built by piwheels may depend on the presence of certain shared libraries. This is resolved by installing apt packages which provide the required shared objects.

We calculate dependencies after building wheels, and show them on the package project pages.

It is possible to discover dependencies yourself using ldd and apt-file. Read more about this process on the piwheels blog.

Sometimes you need to download wheels ahead of time, for installation later, or download the wheels you need using your PC, and then transfer them to a Raspberry Pi which is offline.

To download the wheels on a Raspberry Pi, for use on the same Pi model, it could be as simple as:

mkdir wheels
cd wheels
pip3 wheel <package>

To download the wheels using your PC, you will need to provide additional flags to specify the spec of the Pi. For example, Armv7 wheels (for a Pi 2/3/4) for Bookworm (cp11):

mkdir wheels
cd wheels
python3 -m pip download \
    --extra-index-url https://www.piwheels.org/simple \
    --implementation cp \
    --platform linux_armv7l \
    --abi cp39 \
    --only-binary=:all: \
    <package>

You'll need to alter the flags according to platform and ABI requirements.

Sometimes you need to install the Armv6 wheels, even if you're on a Pi 2/3/4/400/Zero 2, because you intend to use the SD card on multiple models, including Pi 1/Zero.

Note that in almost all cases, the Armv6 and Armv7 wheels are identical, and compatible on both architectures. The only exceptions are opencv and tensorflow.

To ensure the Armv6 wheels are installed on a Pi 2/3/4, you need to find the location of the Armv6 wheels, download them and rename them.

1. Go to the package's project page, scroll down to the Files section, and find the file you need.
2. Copy the full URL of the file location, e.g. https://www.piwheels.org/simple/tensorflow/tensorflow-1.14.0-cp37-none-linux_armv6l.whl
3. Download the file
4. Rename the file, changing armv6l to armv7l
5. Use pip to install the file

wget https://www.piwheels.org/simple/tensorflow/tensorflow-1.14.0-cp37-none-linux_armv6l.whl
mv tensorflow-1.14.0-cp37-none-linux_armv6l.whl tensorflow-1.14.0-cp37-none-linux_armv7l.whl
pip3 install tensorflow-1.14.0-cp37-none-linux_armv7l.whl

Alternatively, simply install the packages as normal on a Pi 1/Zero.

Navigate to the project page for the package, and you should see which versions are available for each Python version. If a build failed, it will show a red cross. If you click the build status icon, you'll see the build log that shows the output from the build. This may indicate where the build failed, and why. See the following questions on reporting issues to us.

Issues with packages are tracked within the piwheels/packages GitHub repository.

Navigate to the project page for the package, and you should see which versions are available for each Python version. If your attempt to install a package failed, check if this is because we don't have a successful build for the package, or the version your require. Note that installing one package may result in failure to install another dependent package. If a build failed, it will show a red cross. If your issue is that the package, or a version of a package, is not available on piwheels, please see the following question on missing packages. If you determine there is an issue with the way a package was built by piwheels, please open an issue against the package in question.

At the bottom of the project page, you'll see "Search issues for this package". Clicking this will search GitHub for issues reported about this package. If there are already issues for the package, links to those issues will be shown. If not, you can click one of the links below this to report one. Please open a new issue, and we'll follow up as we investigate.

Issues with packages are tracked within the piwheels/packages GitHub repository.

Navigate to the project page for the package, and you should see which versions are available for each Python version. If a build failed, it will show a red cross. If you click the build status icon, you'll see the build log that shows the output from the build. This may indicate where the build failed, and why.

At the bottom of the project page, you'll see "Search issues for this package". Clicking this will search GitHub for issues reported about this package. If there are already issues for the package, links to those issues will be shown. If not, you can click the link below this to report one. If a version has a failed build, or all builds failed for this package, please open a "missing package" issue, and we'll follow up as we investigate and try to build the package if possible.

• If you find a missing package, open an issue and complete the issue form in full.
• If you see a missing package issue, you can help by trying to build it yourself, and try to identify the cause of the failure. Report your findings to us by replying to the GitHub issue.
• If you want to seek out missing packages, refer to the project board or issue list.

This is a summary taken from a blog post How you can help.

We've seen some (very few) reports of hash mismatches when people are using piwheels.

First of all, don't ignore the hash mismatch — it's important to verify that the file you downloaded is the file you were expecting.

You need to download the file, verify it, and install it manually:

1. Go to the package's project page, find the version you need, and open up the list of files. Choose the right file for your Python version and architecture.
2. Copy the full URL of the file location (without the checksum which follows the hash), e.g. https://www.piwheels.org/simple/tensorflow/tensorflow-1.14.0-cp37-none-linux_armv7l.whl
3. Download the file:

   wget https://www.piwheels.org/simple/tensorflow/tensorflow-1.14.0-cp37-none-linux_armv7l.whl

4. Check the sha256sum of the file:

   sha256sum tensorflow-1.14.0-cp37-none-linux_armv7l.whl

5. Verify that it matches the checksum after the hash in the URL on the project page:
6. If it matches:
   • That means pip was timing out trying to download the file, and you ended up with a corrupted file. This is a bug in pip which is difficult to reproduce.
   • It's safe to install the wheel, so you can use pip to install directly from the file: pip3 install tensorflow-1.14.0-cp37-none-linux_armv7l.whl
7. If it doesn't match:
   • Rename the file extension from .whl to .zip and try to open it as a zip file. If it opens correctly, it should look like a Python package. If it does, that means the hash mismatch is genuine, so please open an issue and understand the risk before proceeding to install it.
   • If not, it's probably corrupted (which expains your original problem). Try downloading it again, and check your internet connection is stable.

If you delete a package or version from PyPI, it will also be deleted from piwheels, and any files relating to the package or version will be removed. In the case of version removal, the project page will be updated to remove the version in question. In the case of package deletion, the project page will be deleted.

Alternatively, package maintainers have the ability to "yank" releases from PyPI. Yanking a release allows authors to effectively delete a version's files, without breaking things for people who have pinned to exactly a specific version. Releases yanked from PyPI will be reflected in piwheels, both in the simple index and visually on the project page. Read more about "yank" in PEP-592.

Yes! Read about the piwheels JSON API.

Please send an email to ben@piwheels.org.

Please add your question on GitHub, and we'll try to help, and consider adding an entry here.