PyPI is the Python Package Index. It is a repository for python packages that makes downloading and installing new packages easy. If you have ever used pip install <package_name>, you've used PyPI. It turns out that is is relatively simple to upload your own packages to PyPI. If you want to share your open source python project with the world, then this is the best way to do it. But even if you aren't interested in launching a project, uploading your own packages to PyPI makes using them easier.

I recently ran into an issue where I wanted to use a little python package I write for expanding macros. I don't particularly care if anybody else wants to use module, although it's available for ]download on [github(https://github.com/CD3/macro_expander), its just a little utility that I put into a module so I could reuse it.

I recently started using pipenv, so every project gets its own virtual environment, and I can easily manage the packages installed in the virtual environment with pipenv install <package_name>. This will just run pip to install packages from PyPI.

Now, my macro_expander module provides a setup.py script, so I can install it with pythyon setup.py install or pip install .. That means I can easily install my module into my project's virtual environment by first activating the environment with pipenv shell, and then running pip install .. This works fine, but it is kind of a pain if I want to work on the project on a different computer because I have to repeat these steps. By installing it from a local directory, pipenv can automatically install it from its Pipfile.

The solution is to upload my module to PyPI.

First, you will need an account. That pretty simple, just go over to https://pypi.org and click on "Register". Next, you need to make your project "publishable", which means you need to write a setup.py script. I already had one in place for doing local installs, so that was no problem. If you don't have a setup.py script, they are pretty easy. You can read the official documentation, or just google "writing a setup.py script". Once you have a setup.py script, you should test that it works, which you can do by creating a virtual environment and then installing your module into it.

$ virtualenv test-env
$ source test-env/bin/activate
$ pip install .

If that works, you are ready to package your module for PyPI. Note: the user documentation for the click module has a great set of instructions for writing setup.py scripts here.

Next, you need to install twine. Again, I use pipenv, so I just went to my macro_expander project directory and ran

$ pipenv install twine

Now your all set to build and upload your package. First build:

$ pipenv run python setup.py sdist

This will create a directory named dist/ with your built package in it. No you just upload it with twine:

$ pipenv run twine upload dist/*

You be asked for your username and password, and then twine will upload the package.

That's it. Now you can go to another project and install your package.

$ cd to/other/project
$ pipenv install your-package-name

The only thing you may want to consider is naming your package so that it does not collide with somebody else's package.

If you want more details, checkout this blog by joelbarmettlerUZH. This is where I first learned how to upload packages to PyPI. Thanks to joelbarmettlerUZH.