A Beginner’s Guide to Publishing Packages on the Python Package Index (PyPi)

Published in

Analytics Vidhya

6 min readJun 23, 2020

Here, we are going to learn the steps to publishing a basic python package.

When I decided to publish a Python package for the first time, I had difficulties finding resources for the beginner. So, here it is- the basics to publishing a Python Package in PyPi and getting your work out there.

Why Develop a Python Package?

By developing and publishing a python package, you will enable others to use (and cite!) your work. Packages can help facilitate collaboration with others doing similar work and get you publicity on your work! Even internally, using a Python Package can help standardize your workflow. So what are you waiting for? Get that code up on PyPi and start collaborating and standardizing your workflow.

Basic Assumptions

This is what I expect you to do prior to the start of the tutorial:

1. Install pip if you don’t already have it.

2. Get a PyPi account if you don’t already have one (I recommend using a non-university, professional email for this)

3. Have some function-based (should already be formatted as functions) code that you want to publish as a PyPi package

4. Have a GitHub and have a basic understanding of git

Deciding on a License

First things first, decide on a license for your package. Here is a helpful resource for deciding on the best license for you!

Naming your Package

Pick a unique name that is memorable and relates to what the package does. Keep in mind that Python packages should have short, all lowercase names and that the use of underscores is discouraged. You can search on pypi.org to see if your name is unique. You should always check and make sure your desired python package name is not going to override anything (for example, ‘list’ already has a meaning in Python- you would not want to name your package “list”).

Check here for names to avoid.

Documenting your Code

This is an important section, and you will probably spend most of your time here! Think of all the ways others may want to use your code and make sure your functions are either a) generalize-able (preferred) or b) very well documented so others can use your code easily.

Document each function using the following comment at the beginning of each function:

Repository

Now that you have gone through and well-documented your code, let’s make the GitHub repository where your package will live. Enter the exact name of your package as the repository name. Make sure the repository is set to public, that you have initialized the repository with a README, and you have added your selected license.

Now, your repository should look like this:

It’s time to pull open your terminal (Mac) or git Bash (Windows) or however you associate with your git. Change directories to the directory where you want your package to live. I recommend creating a directory called “Packages” to keep all of your packages in one place:

Formatting your repository

It is time to format your repository. There are MANY ways to do this. For this beginner tutorial, I am going to show you the simplest way of doing this but if you want to know more or have more complex code architectures requiring different formatting, I have included references at the end of this tutorial.

Currently, you have a README.md and a LICENSE file in your repo. You are going to add a directory (folder) inside the repo named ‘yourpackagename’.

Now your main directory should contain:

LICENSE
README.md
Packagename (folder)

init.py

Navigate into the directory you just made. Here is where you are going to add a python file called __init__.py. Open this .py file in your favorite editor. Add your dependencies at the top, your documentation, and your functions, as shown:

setup.py

Navigate back to your main directory, where your README.md is. Here, you are going to add a python file called setup.py. I recommend copy/pasting the below code and just filling in your information:

setup.cfg

In your main directory, create a file called setup.cfg. I recommend copy/pasting the below code.

README.md

The README is one of the most important parts of your Python package because it tells people how to install it and how to use it. A well-done README is necessary for having a reusable Python package. I recommend using Dillinger for creating READMEs. If you use Dillinger, you can download the README you make and just replace the one currently in your directory.

Now your main directory should contain:

LICENSE
README.md
setup.py
setup.cfg
Packagename (folder)
(Inside Packagename folder): __init__.py

Add and commit these files via git.

Setting up versioning

This step will make it easier for you to make edits down the road, so don’t skip it!

Push your repository back to GitHub (origin master).

Now, navigate to your GitHub repository. Under the releases tab, you are going to “Create a new release”. The version should be the same as in your setup.py file (initially 0.1 if you have been following along).

In order to get the source code, right-click on the tar.gz link and click “Copy Link Location” (other browsers may say “Copy Link Address”). Update the setup.py file in the “download_url” field with this link address.

Uploading your package to PyPi

Wait. Test your package. And test it again.

Okay, now we are ready to upload to the Python Package Index!

Open the terminal (Mac, Linux) or Windows Powershell (Windows).

First, you will install twine. You only have to do this the first time. Once installed, twine will make it super easy to update our packages and upload to PyPi.

If you go to pypi.org, you should now be able to see your package in ‘Your Projects’ and you should be able to search for it! Test your package to make sure it works by installing it yourself:

pip install packagename

Updating your package

Low and behold, you found a bug in your code even after rigorously testing it. Or maybe you have a new feature to deploy in your package. Either way, updating your package in PyPi doesn’t have to be a headache. Follow these steps:

1. Make your changes in your local repository.

2. Update version # in setup.py file

3. Push to GitHub, make a new release as described above, and update setup.py download_url field with the new release tar.gz file

4. Repeat steps to upload package to PyPi

Adding tests

It is good practice to add a test_ directory in your repository with the following:

test_code.py (test code testing all functionalities of your package)
test_results (markdown, jupyter notebook, or text file with results of test_code.py so folks testing your code can ensure it is working properly)
test_file.csv (if your package functions with data, this file is a small bit of de-identified data to ensure your package works)

Getting the word out about your package

Let people know that they can install your package via pip:

pip install packagename

Write a blog about your new package, post the package on LinkedIn and Twitter, or post to your personal website!

If you want to broaden the reach of your package, I suggest looking into the Journal of Open Source Software (JOSS) and the Journal of Open Research Software (JORS).

Now, you are ready to embark on more challenging python package development! Check out the references below if you want to dive deeper into developing Python packages and modules.