The Python Package Index (PyPI) is the official repository for python packages. It is the magic behind pip install <your-awesome-package>. Recently I published a package there (see its PyPI page here) and I will share the procedures in this post.


Before uploading a project to PyPI, we need to

  • create account on PyPI
  • prepare packages and distribution information for your project

The account registration is straightforward. For packaging and distribution, we need the following tools

pip3 install twine setuptools wheel

All meta data for the package should be in a python file called You can see my example here. When ready, run

python3 sdist bdist_wheel

It will create a folder called dist with the source tarball file and wheel file in it.

upload to PyPI

Uploading to PyPI is simply one command

twine upload dist/*

If no error occurs, you should be able to see the release at<your-package-name>/. And the package is installable from any machines equipped with pip.

Note that PyPI does not allow overwriting an existing release. Thus the version in needs to be bumped up for each upload.

To save the typying of user login for the upload, we can create a runtime configuration file ~/.pypirc

index-servers =

username: yourusername

You can also put your password there as password: yourpassword and limit the file’s permission

chmod 400 ~/.pypirc

using as PyPI project description

Since Apr 2018, GitHub style markdown file can be used directly as PyPI project description page. All one needs to do is to set the long_description in, as follows

long_description = None
with open('') as f:
    long_description =