Suppose we have written a Python package, like pypdb. Our goal is to make it possible for users to install the package using PyPI:

$ pip install pypdb

Initialization and setup

  • Make an account on PyPI. Note: Depending on your project scale, consider also making a matching account on TestPyPI for testing
  • In your computer’s home folder , create a .pypirc file, which allows authentication

    [distutils] index-servers = pypi pypitest

    [pypi] repository= username=your_username password=your_password

Set the appropriate permissions

$ chmod 600 ~/.pypirc

Setup project structure

Follow the instructions here for properly setting up a Python project. In the root directory, add a file setup.cfg containing the following

description-file =

Development and testing

During development, continuously update your local installation by having a Terminal window directed to the location of, and periodically run

pip install --upgrade .

This is much easier than trying to import locally from a path

Updating existing package

Update to the latest version number. Pay attention to the number of digits after the decimal: 1.3 will be counted as a lower release number than 1.299

Update and push the new version number to GitHub

$ git tag 0.5 -m "latest version"
$ git push --tags origin master

Make a distribution

python sdist bdist_wheel

Install twine using pip if needed. Now upload the new distribution via twine

python3 -m twine upload --skip-existing -r pypi dist/* --verbose

Enter PyPI credentials when prompted to do so


Issues authenticating when uploading to PyPI from Terminal

You might need to make a file at ~/.pypirc containing

index-servers =

username: <username>
password: <pass>

This will help avoid having to login elsewhere. If you are having problems logging in, check the contents of this file