What is a Python wheel?

Python wheels are a pre-built binary package format for Python modules and libraries. They are designed to make it easier to install and manage Python packages, by providing a convenient, single-file format that can be downloaded and installed without the need to compile the package from source code. They are designed to replace the older egg format and provide a number of benefits over eggs and other package formats, such as easier installation and better support for versioning and dependencies.

When you install a package provided in traditional .egg format the following steps are performed by the system.

1. The system downloads a TAR file (tarball).
2. The system builds a .whl file by calling  setup.py
3. The system installs the actual package after having built the wheel.

This process of downloading and compiling the tar file makes the whole process cumbersome and time-consuming.

What are the advantages of using Python Wheels?

One of the key advantages of using wheels is that they allow Python modules to be installed and used without requiring a build process. This means that users can simply download a wheel package and install it using the pip command, without needing to compile the package from the source code or install any additional dependencies. This can significantly speed up the installation process for large or complex Python packages.

Different types of  Python Wheels

In the Python ecosystem, there are three main types of wheels:

Pure-python Wheels

These are built from source code that only depends on the Python Standard Library. They are platform-independent, meaning they can be installed on any system that has a compatible version of Python installed.

The following command is used for building a pure-python wheel from the setup.py of a package:

python setup.py bdist_wheel

This will create a .whl file in the dist directory that can be installed on any platform with a compatible version of Python.

Universal Wheels

These are built from source code that depends on the Python Standard Library and additional, non-platform-specific dependencies. They are also platform-independent but may have additional dependencies that need to be installed alongside the wheel.

The following command is used for building a pure-python wheel from the setup.py of a package:

python setup.py bdist_wheel  --universal

This will create a .whl file in the dist directory that can be installed on any platform with a compatible version of Python and the required dependencies.

Platform Wheels

These are built from source code that depends on the Python Standard Library and additional, platform-specific dependencies. They are not platform-independent, and can only be installed on systems that have the same platform as the one used to build the wheel.

The following command is used for building a pure-python wheel from the setup.py of a package:

python setup.py bdist_wheel --plat-name=macosx_10_6_intel

This will create a .whl file in the dist directory that can only be installed on macOS systems with an Intel processor running version 10.6 or later.

Filename structure of Wheel

A sample structure of a wheel filename can be seen below:

In this format, the {distribution} field specifies the name of the Python package, the {version} field specifies the version of the package, the {build} field specifies the build number of the package, the {python} field specifies the version and implementation of Python used to build the package, the {abi} field specifies the Python ABI (Application Binary Interface) used, and the {platform} field specifies the platform-specific details of the package.

{distribution}-{version}-{build}-{python}-{abi}-{platform}.whl

By using this universal naming scheme, wheels ensure that users can easily identify and install compatible packages on any version of Python that supports the wheel format. This makes it easier for developers to distribute their packages and for users to install them, without needing to worry about compatibility issues. Below is a list of some wheel filenames for the MySQL client.

• mysqlclient-1.3.13-cp36-cp36m-win_amd64.whl
• mysqlclient‑1.3.13‑cp36‑cp36m‑win32.whl

These two are the wheel files of the MySQL client of version 1.3.13 for different systems like `amd64`, and `win32` with a mere look at these filenames most technical users can easily understand which is the supported version for their system. To install a wheel package using pip, you can use the pip install command followed by the path to the wheel file. 

pip install mysqlclient-1.3.13-cp36-cp36m-win_amd64.whl

Build a Wheel from Source Code

Suppose you want to create a wheel file from your source code. You can easily do the same by following the below procedure.

The contents of the source directory for a Python package will vary depending on the specifics of the package, but generally, it should include the following:

• A setup.py file: This file is used to configure the package and its dependencies for installation.
• The package source code: This will typically be organized into subdirectories based on the package’s modules and submodules.
• Any necessary data files: If the package needs any data files (e.g. configuration files, sample data) for its operations, they should be included in the source directory.
• A LICENSE file: This file should contain the license under which the package is distributed.
• A README file: This file should provide an overview of the package, including its features and usage instructions.

Here is an example of the structure of a Python package source directory:

The directory structure for python Package source library

In the above image, the package has a setup.py file and a package_name directory containing the package’s source code, as well as a data directory with sample data and a LICENCE and README file.

Example

Following is an example of a setup.py file for a Python package. The setup() function is used to configure the package for installation. It takes a number of keyword arguments, including the package name, version, and description, as well as the package dependencies and a list of the package’s source code directories. This information is used by the pip command to install the package.

Python3

from setuptools import setup, find_packages

# Package metadata
name = 'package_name'
version = '1.0.0'
description = 'A brief description of the package'

# Package dependencies
dependencies = [
    'dependency1>=1.0.0',
    'dependency2>=1.5.0'
]

# Package setup
setup(
    name=name,
    version=version,
    description=description,
    packages=find_packages(),
    install_requires=dependencies
)

Steps to Create the Wheel File

Step 1:  First, make sure you have the wheel package installed:

pip install wheel

Step 2:   Navigate to the directory containing your package and run the following command:

python setup.py bdist_wheel

Output:

This will create a .whl file in the dist directory of your package. 

Output after running the setup.py file

Step 3:  Now go to the dist directory inside your package folder and Install this wheel using the following pip command:

pip install package-name-1.0.0-py3-none-any.whl

Output:

Output of the pip install package-name.whl command