Simply add the following to
Upgrade pip to >=9.0.1 using
sudo pip3 install pip
--upgrade and follow the Raspbian Stretch
Install pip >=9.0.1, and follow the Raspbian Stretch instructions.
If you had to upgrade pip to >=9.0.1 you may also need to
upgrade pip within the virtual environment with
pip --upgrade. If not (e.g. in Raspbian Stretch), pip
should honour your
/etc/pip.conf file and use
piwheels as configured.
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
$ sudo pip3 install numpy --extra-index-url https://www.piwheels.org/simple
Alternatively, to only use piwheels, use the
--index-url option, for example:
$ sudo pip3 install numpy -i https://www.piwheels.org/simple
$ sudo 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 the
extra-index-url configuration in
/etc/pip.conf to avoid piwheels permanently, 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: https://pypi.python.org/simpleor 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 https://pypi.python.org/simple
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.
You don't need to do anything. All package releases on PyPI are automatically processed by the piwheels project.
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.
piwheels attempts to build every release of every package on PyPI. Some build attempts are unsuccessful, and these versions will not be available on piwheels. While some versions of a given package may be available, others may not have been built successfully. 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.
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:
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 Raspbian operating system on Raspberry Pi 3 hardware.
All current Raspberry Pi models (as of November 2018) are supported:
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
pyqt installed, the wheel will depend on
the user also having
pyqt installed. If it is built
pyqt, the user can use
If you find an issue with a package installed from piwheels, please submit an issue on github.
Currently, piwheels supports Python 3 only. While most packages available will work in any version of Python 3, but some packages are only compatible with the minor version with which they were built.
The source code for the piwheels project can be found on GitHub at github.com/bennuttall/piwheels.
The piwheels project is hosted on a cluster of Raspberry Pi 3s provided by Mythic Beasts.
The original build run was completed by a total of 20 Raspberry Pis, and now a smaller cluster (fewer than 5 Pis) 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
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.
While the hardware in Raspberry Pi 1 and Zero is Armv6, Pi 2 is Armv7, Pi 3 is 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 2, 1 or Zero, we simply provide Pi 3-built wheels
armv6l, with a few exceptions (some packages,
like opencv and tensorflow, are built with optimisations available
on Pi 3).
Some wheels may work on other Arm platforms, but we can't
guarantee this. Pure Python wheels will certainly work, but
there's a much smaller speed increase installing from wheels over
source distribution. Arm platform wheels on piwheels are tagged
armv7l but actually both
contain Armv6-compatible code, which may not work on true Armv7
See the following answer.
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.
No - we can't. Only package maintainers can upload files 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
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
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.
ImportErrorwith 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.
It is possible to discover which packages are required by using
apt-file. Read more about this
process on the piwheels blog.