Python Wheels

What are wheels?

Wheels are the new standard of Python distribution and are intended to replace eggs. Support is offered in pip >= 1.4 and setuptools >= 0.8.

Advantages of wheels

1. Faster installation for pure Python and native C extension packages.
2. Avoids arbitrary code execution for installation. (Avoids setup.py)
3. Installation of a C extension does not require a compiler on Linux, Windows or macOS.
4. Allows better caching for testing and continuous integration.
5. Creates .pyc files as part of installation to ensure they match the Python interpreter used.
6. More consistent installs across platforms and machines.

What is this list?

This site shows the top 360 most-downloaded packages on PyPI showing which have been uploaded as wheel archives.

• Green packages offer wheels,
• White packages have no wheel archives uploaded (yet!).

Packages that are known to be deprecated are not included. (For example distribute). If your package is incorrectly listed, please create a ticket.

This used to show the all-time most-downloaded packages. The all-time list is no longer available, and the packages in the last-30-days list will change to reflect more closely what the Python community is using.

This is not the official website for wheels, just a nice visual way to measure adoption. To see the authoritative guide on wheels and other aspects of Python packaging, see the Python Packaging User Guide.

My package is white. What can I do?

Pure Python

If you have a pure Python package that is not using 2to3 for Python 3 support, you've got it easy. Make sure Wheel is installed…

pip install wheel

…and when you'd normally run python setup.py sdist, run instead python setup.py sdist bdist_wheel. For a more in-depth explanation, see this guide on sharing your labor of love.

Note: If your project is Python 2 and 3 compatible you can create a universal wheel distribution. Create a file called setup.cfg with the following content and upload your package.

[bdist_wheel]
universal = 1

Warning: If your project has optional C extensions, it is recommended not to publish a universal wheel, because pip will prefer the wheel over a source installation.

Note: To include your project's license file in the wheel distribution, specify the license_files key in the [metadata] section. This helps comply with many open source licenses that require the license text to be included in every distributable artifact of the project. This option requires wheel 0.32 or newer.

[metadata]
license_files = LICENSE

C extensions

PyPI currently allows uploading platform-specific wheels for Windows, macOS and Linux. It is useful to create wheels for these platforms, as it avoids the need for your users to compile the package when installing.

You will need to have access to the platform you are building for. Projects like cibuildwheel or multibuild provide tooling and guidance to build binary wheels for different platforms using various continuous integration (CI) services.

Something's wrong with this page!

Fantastic, a problem found is a problem fixed. Please create a ticket!

You can also submit a pull-request.

Note: Requests for behavioural changes in the packaging tools themselves should be directed to distutils-sig and the Python Packaging Authority.

Thanks

Thanks to the Python 3 Wall of Superpowers for the concept and making their code open source, Donald Stufft for his help on IRC, James Turnbull for the intro copy, and George Hickman for pointing me in the right direction as usual.

Thanks also to the many contributors.