Last Updated: 2025-10-22

Wheels

• pip will use wheels (.whl) to install wherever possible
• These "just work" in that the compilation steps are already done and you need min dependencies on the machine installing things.
• when installing directly from a VCS link (e.g. GitHub URL), you will not, however get a wheel file
• wheels are system architecture dependent and even if a wheel is present, pip may go with source distibution instead if it determines the wheel is incompatible with the current system. This explains the historic challenges with getting psycopg2 working well.
• A wheel is a type of "built distribution". In this case, built means that the wheel comes in a ready-to-install format and allows you to skip the build stage required with source distributions.
• A wheel is essentially a zip file with a specially crafted filename that tells insteallers what python version and platforms are supported. The format is {dist}-{version}(-{build})?-{python}-{abi}-{platform}.whl - e.g. cryptography-2.9.2-cp35-abi3-macosx_10_9_x86_64.whl (cp35 is CPython 3.5).
• If you want the wheel to run on any platform, then you can replace {python}-{abi}-{platform} with py3-none-any.whl. This can be generated with python setup.py bdist_wheel --universal. It will probably end up in the dist folder.
• If you want to force pip to install the wheel, use pip install --only-binary. And if you want it to NOT use the wheel, use pip install --no-binary

Source Distribution

• If no wheel file is available, pip retrieves a "source distribution" or sdist, which is basically the opposite of a wheel. It can contain code of any language (e.g. JS, C++ etc.) and compilation happens on the installer's side
• Some distributions contain a directory called <package-name>.egg-info. This metadata helps with building and installing the package, but user’s don’t really need to do anything with it

Debugging

• you can see what pip is doing during the install of a package by looking for whether it downloads a .whl file or whether it builds one during a pip install x

Developing / forking libraries

• If you want to upload your wheel for distribution, do pip install -U twine to get the tool you need (twine) and then do twine upload dist/* (you'll need an account)
• You can force pip to install from a local wheel by giving a reference to the exact file - e.g. in requirements.txt ./local_wheels/ABC-0.0.2-py3-none-any.whl
• from a developer's perspective, you can get a wheel out by running $ python setup.py bdist_wheel
• from a developer's perspective, you get a source distribution when running $ python setup.py sdist