Menu

FAQ

How do I install packages from piwheels?

Raspbian Buster or Stretch:

You should have a /etc/pip.conf file 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.

Raspbian Jessie:

Upgrade pip to >=9.0.1 using sudo pip3 install pip --upgrade and follow the Raspbian Buster/Stretch instructions.

Other operating systems:

Install pip >=9.0.1, and follow the Raspbian Buster/Stretch instructions.

How do I install a package from piwheels within a virtual environment?

If you had to upgrade pip to >=9.0.1 you may also need to upgrade pip within the virtual environment with pip install pip --upgrade. If not (e.g. in Raspbian Buster or Stretch), pip should honour your /etc/pip.conf file and use piwheels as configured.

How do I install a package from piwheels without changing my pip configuration?

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:

$ sudo 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:

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

or

$ sudo pip3 install numpy --index-url https://www.piwheels.org/simple
How do I install a package from PyPI (not from piwheels)?

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:

$ sudo 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:
$ sudo pip3 install tensorflow --no-binary grpcio
How much time does piwheels save?

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.

I maintain a package on PyPI. How do I publish it on piwheels?

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.

Why is a package I maintain not available on piwheels?

Some packages fail to build, for various reasons. If you would like to investigate, try building the package yourself on a Raspberry Pi 3 with a Raspbian Lite image by running pip3 wheel <package>. If you find you are able to successfully build the package (for example, by installing some build dependencies), please open an issue on github and we'll try to resolve it. Also see the following answer.

Why are some versions of a package available on piwheels and other versions are not?

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 open an issue on github and we'll try to resolve it.

How long does it take for a new release to become available on piwheels?

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 Raspbian 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).

Does piwheels use cross-compilation?

No. All wheels are built natively on the Raspbian operating system on Raspberry Pi 3 hardware.

Which Raspberry Pi models are supported by packages provided by piwheels?

All current Raspberry Pi models (as of July 2019) are supported:

  • Raspberry Pi 4
  • Raspberry Pi 3 (including B+/A+)
  • Raspberry Pi 2
  • Raspberry Pi 1 (including B+/A+)
  • Raspberry Pi Zero

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

I installed a package from piwheels and it doesn't work as expected

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 submit an issue on github.

Which Python versions does piwheels support?

Currently, 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 Raspbian releases:

  • Raspbian Jessie - Python 3.4
  • Raspbian Stretch - Python 3.5
  • Raspbian Buster - Python 3.7
Where can I find the piwheels source code?

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

What infrastructure does the piwheels project use?

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

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

The package I installed took a long time to install, despite being available on piwheels.

First of all: check your pip configuration and confirm that piwheels is in fact being used. You should see downloading from https://www.piwheels.org.

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.

Why are the wheel files are tagged with Armv6 and Armv7? What about Armv8?

While the hardware in Raspberry Pi 1 and Zero is Armv6, Pi 2 is Armv7, Pi 3 and 4 are Armv8, the Raspbian operating system images provided on raspberrypi.org 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 or 3 are tagged armv7l. Since wheels built on a Raspberry Pi 3 will work on a Pi 4, 3, 2, 1 or Zero, we simply provide Pi 3-built wheels renamed armv6l, with a few exceptions (some packages, like opencv and tensorflow, are built with optimisations available on Pi 3).

Also see the following answer.

What about aarch64?

aarch64 is the 64-bit execution state of the ARMv8 instruction set architecture. It's possible to run an aarch64 operating system on Raspberry Pi 3 and 4, but the officially supported operating system, Raspbian, does not currently build for aarch64. Since piwheels.org only builds wheels on Raspbian, no aarch64 (armv8l) wheels are provided. Other projects may wish to use the piwheels project source code to run an aarch64 wheel repository for other distributions.

Will wheels provided on piwheels work on other Arm platforms?

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

Can I install packages from piwheels on my PC/Mac to speed up installations?

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 of any help.

Are you going to upload all the wheels to PyPI?

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.

I'm a package maintainer. Can I upload an Arm wheel to PyPI?

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 indentical 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.

I'm a package maintainer. How can I remove a wheel from piwheels?

Open an issue on github 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).

Note that we only currently track package additions from PyPI upstream; we don't honour package removals from PyPI hence removals must be requested manually. Frankly, package removal is an area fraught with difficulty. Even if we remove a given package from piwheels there's no guarantee some downstream mirror hasn't already got it, or another mirror of PyPI. The best solution to ensure your users avoid a given release is to cut a new release of your package with a higher version number.

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 via a skip flag in our database.

My package is really popular, so why are the download stats so low?

We only log downloads from piwheels.org, not from PyPI. If your package is pure Python, and you submit wheels to PyPI (as you should), users will get the file from PyPI, not from piwheels. The only downloads from piwheels for these packages will be if people are explicitly choosing to download 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/Raspbian, people could be installing your package with apt, rather than pip.

I installed a package from piwheels and I get an ImportError with the message "cannot open shared object file".

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.