Creating a Wheel for Python Package

Wheel For Package

Packages are an essential element in Python that improve the factor of code reusability. By using packages, we can use code written by others and get others to use our code. There is a very interesting type of data file which is called a wheel, which can be used to create a package and make it globally available, the how, why, and what of this wheel file is extensively covered in the article below. Let’s learn about creating a wheel file for our packages.

What are Packages in Python?

Python packages are containers/folders that contain sub-packages and modules in one place. Including the ‘’ file in this directory is essential. 

There is a difference between Python packages and Python modules. To get a better understanding of the difference, refer to this link.

The ‘’ is an initialization file, which could be empty or contain information about importing modules.

Packages usually provide some functionality that can be used by other programs by using imports[To understand Python imports, refer to the preceding link]. 

What Wheels in Python?

Wheel files are essentially Python packages. Every time you use the terminal to install a package using ‘pip’, you are actually installing a wheel file. Wheel files can be identified as files with the ‘.whl’ extension.

pip install numpy   #This will install numpy wheel file

To get a better visual understanding check out any package on pypi. You might notice that almost all the files inside a package are wheel files.

Why Create a Wheel for Our Python Packages

Creating a wheel file for our Python packages is essential so that our packages can be distributed to various places. Wheel files are comparatively faster than source distribution, and they do not occupy much space as they are smaller compared to the source distribution.

Once you have created a ‘.whl’ file, you can just simply install it using pip in your system as shown below.

pip install <created '.whl' file>  #Directly install a previously written file.

In this article, we will study not only the ‘why’ of creating ‘.whl’ files for Python packages but also the ‘how’ of creating the ‘.whl’ file. I will be using PyCharm as an IDE. The choice of IDE is completely yours.

Preparing a Package

To begin with, first, we will be creating a package in which we will be creating a ‘.whl’ file later on in the article.

Let’s begin by creating a package, to do so, first start by creating a directory that will be staged as a package later in your current project.

Inside the newly created directory, create a ‘.py’ file in which we will create some functionality of our package. We will also be needing the ‘’ file in the same directory.

Directory Structure
Directory Structure

[By now, your directory should be structured like this if you have followed the article by far.]

Let’s create a calculator package with some basic functionalities.

#This is how your ‘’ will look like

def add(a,b):
       return a+b

def subtract(a,b):
       return a-b

def multiply(a,b):
       return a * b

def divide(a, b):
       return a / b

Let’s write some code in the ‘’ file so that it starts recognizing our calculator package.

# This is how your ‘’ file will look like

from .calc import add, subtract, divide, multiply

After this, you will need the ‘setuptool’ package. You can install it via pip using the below command.

pip install setuptools  #This will install the setup tools package

The ‘’ file

Now we will begin setting up the ‘’ file which is another import file. Starting by creating a new ‘.py’ file outside the package directory but inside the same project. Name the new file as ‘’.

#This is what your ‘’ file should look like.

from setuptools import setup, find_packages

    name="calc", #Name
    version="1.0", #Version
    packages = find_packages()  # Automatically find the packages that are recognized in the ''.

Building/Creating a Wheel

By far, we have created a package that is capable of being imported only in that specific directory and not anywhere else, but if you’ve been following along this far, I definitely think that you want your package to be able to be imported from anywhere you want.

So let’s see if we can do something about this.

First, get into the terminal of your IDE and navigate to the parent directory of your package, which in my case is ‘test_whl_pkg’. Once you’ve reached the parent directory, write the below statement in the terminal.

python3 bdist_wheel  #Write inside terminal after navigating to the parent directory.

The ‘bdist_wheel’ keyword is the actual game changer which creates a binary distribution of your file as a wheel. Once you type the statement, you will see that some processing is happening, as shown below. It could take a couple of seconds, depending on your machine.

Terminal Status
Terminal Status

That’s it! You have finally created a wheel for your Python package. You might see some new directories that have been loaded in the sidebar.

Just simply open the ‘dist’ directory, and there it is, your very own wheel which you could easily import from anywhere on your computer. To install, first, copy the name of the wheel from the ‘dist’ directory and then import it using pip from your terminal.

New Directory Structure
New Directory Structure
pip install <name_of_wheel_in_dist_directory>

Once you run this line and if there are no errors, it will load the package, and you will be able to access the package from anywhere outside your current directory in your machine, and you can access the functionality of your package just like you do with any other package or module that you import.

Successfully Installed python package.
Successfully Installed


Basically, we first start by creating a package as per our requirement and give it some functionality, and then we create an ‘’ file in which the package is marked, and it is made to recognize the package.

After doing this, we create the ‘’ file in which we mention the name, versions, and other characteristics of our package.

Lastly, we navigate to the parent directory of our package and create a wheel file using the ‘bdist_wheel’ command according to the parameters mentioned in the ‘’ file.

If there are no errors in this process, you will soon see a dist directory in the current directory in which you will find the wheel that you’ve just created and which can be accessed by using the pip command from anywhere on your machine and can be used just the way any other package is used which is installed from ‘pypi’.


Official python packages documentation.