Programming Python

Would you like to share your code with the worldwide community of Python developers?

Create your own Python package and publish it into PyPI

In this article, you will find simple steps to convert your code into a Python package, upload it to the Python Package Index site a.k.a PyPI repository.

Let’s start!

I am assuming most of the people, who are reading this article, have already run the command below. But, what happens behind the scenes?

$pip install pandas

At the moment you run the command pip install you are accessing the PyPI site to download a Python package. The site is a repository of software for the Python programming language.

Prepare your code to share

In this article, as an example, I am going to use a couple of programs to be converted into a Python package. This code is an easy game able to “guess” the number into the player’s mind. You can see the code in my GitHub repository.

Step 1: Create the file

Create a file named and save it into the same folder your code is. This file tells Python that the folder contains a Python package. The code inside the file gets run whenever you import a package inside a Python program. In this case, my file is importing GuessMyNumber class from the numberGuesserGame module.

Now, I have three files into my folder:

Step 2: Create the file

Go up one level in the directory and create the file.

This important file contains information about the package. Every time you run the command pip, it will automatically look for the file.

It basically consists of a call to the setup function, which receives arguments to specify details of how the project is defined, for example, name, author, version, description, etc.

Step 3: Install your package locally

After you completed steps 1 and 2, everything is ready to install your Python package locally. First, open a terminal and go to the folder containing your package and type the command below. The dot indicates to look for a file in the current folder and install the package in there.

$pip install .

Now, you can stay in that folder or move to a different one to run Python and use your package. Let see the example:

Step 4: Create the License and README files

Come back to the directory containing your package and create two more files:

  • License.txt will tell users the terms and conditions under which they can use your package. I copied and pasted into my file the MIT license
  • will simply tell users what your package is about

Your folder should look like this one below, your package plus 4 files:

Step 5. Generate your source distribution

Once you have all the needed files, use the following command to install the latest version of setuptools package (we used in file).

$ python -m pip install --user --upgrade setuptools

Make sure you are at the same directory where is located and run this command:

$ python sdist

You will see there is a new folder dist containing the tar.gz file that provides metadata and the essential source files needed for installing by pip.

You will also see a ProjectName.egg-info folder, it contains files and metadata needed to be moved to a specific location on a target system. Don’t worry about it, you can ignore it, remove it or learn more about it here.

Step 6. Create accounts for the Test PyPI and PyPI repositories.

Go to PyPI test and PyPI sites and create your accounts, it’s important to remember your passwords, those will be retyped into the command line very soon.

Step 7. Upload your package to the Test PyPI repository

The next step is to install twine, this utility will help you to upload your package to the PyPI repository or other repositories. Once you have installed twine, you won’t need to repeat this step.

$ pip install twine

Open a terminal and type the command below in your command line, it will ask you to provide the user and password you created previously on step 6.

twine upload --repository-url dist/*

Login to the Test PyPI repository and verify that your package is in there. If so, copy the command that is under the package’s name, run it in your command line and, read in your screen the message saying that your package was successfully installed.

pip install -i guesser-game

Step 8. Upload your package to the PyPI repository

Finally, this is the last command you have to run to share your package with the worldwide community of Python developers. Make sure you are at the same directory where file is located.

twine upload dist/*

Now, the package is in the PyPI repository!


It is important to know how to upload your Python package but in my opinion, it is equal or more important to be willing to share your knowledge, collaborate with the community, create a learning culture and find different ways to do things.

For more reference material, you can review