Creating and publishing Python modules

I once developed a simple script to fetch course schedule and plan a timetable for myself. Later, I turned it into a Python module and published it to PyPi. Now, the module can be installed with just a simple pip install command. I would like to share with you how I created a Python module and successfully uploaded it to PyPi.

Creating Python modules

Creating Python modules are easier than most of you might think. All you need is a file named, and it could even be just an empty file! Suppose we have the following files


This creates a Python module named testmod. If we have the following code in

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

Now when you start the Python interpreter from testmod’s parent directory, you can import your testmod module just like any other module you’d like to import

>>> from testmod.main import add
>>> add(9, 7)

There goes our simple Python module! Once you understand the concept, you can build much complex modules with it.

By the way, if you put any Python code in, it will be executed every time you import that module. If you need some initialization done when your module gets imported, you should put that part of the code into

Publishing Python modules to PyPi

Now that you have a simple Python module built, you could publish it to PyPi so that it can be installed via pip install.


Make sure you have everything you need before we continue. You need to have pip, setuptools, and twine installed for your Python interpreter. The first two usually comes with Python, install twine with

$ pip install twine

Configuration files

You need to add some configuration files to your module before you publish it to PyPi. Here we only consider the file that is required.

This is the most important file that you will need. This file should exist in your module’s parent directory. The file specifies how you would like your module configured. It contains a setup() function that includes all that information. Here is an example file.

from setuptools import setup

long_description = """
This is the long description for testmod.

	name = "testmod", # name of your module
	version = "0.0.1", # version of your module
	description = "A short description for testmod.", # a short description
	long_description = long_description, # a long description
	url = "", # project homepage URL
	author = "Someone", # your name
	author_email = "", # your email
	keywords = "testing sample", # keywords for your module
	packages = ["testmod"], # packages to include (we only have one)
	#install_requires = [] # if your project has dependencies, list it here

Creating distributions

You need to create distributions of your project before you could upload it to PyPi. Here we will create a binary distribution which users can just download and use. Run

$ python bdist_wheel --universal

This assumes that your module can be used for both Python 2 & 3 (hence the --universal flag). You will find a dist directory containing your build.

Uploading to PyPi

First register an account at PyPi. Then save your account credentials in ~/.pypirc like this

index-servers = pypi

repository =
username = <your username>
password = <your password>

Next, register your project (if this is the first time you are uploading to PyPi) with

$ twine register dist/testmod-0.0.1-py2.py3-none-any.whl

and upload it to PyPi with

$ twine upload dist/*

There you have it. Your module is on PyPi! You can now install it with pip install testmod. (You may need to wait a few hours for the PyPi index to update)

Note: Please note that the module testmod already exists on PyPi, therefore your commands will fail. I’m only using the name for demo purposes. Use the actual name of your module to run the above commands.


comments powered by Disqus