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=https://pypi.python.org/pypi 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

[metadata]
description-file = README.md

Development and testing

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

pip install -I --no-deps .

This is much easier than trying to import locally from a path. The no-dependencies flag ensures that pip does not try to reinstall all of the dependencies, especially packages like numpy that may have been installed using conda.

Upload a new package to PyPI

Create a distribution

python -m build

Do a dry-run upload to TestPyPI

twine upload -r testpypi dist/*

If the dry-run is successful, upload to PyPI

twine upload dist/*

Updating existing package using pyproject.toml

Update pyproject.toml 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

In your current environment, install the buildtools if neededed via pip install buildtools. Now build the package

$ python -m build

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

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

Update setup.py 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 setup.py 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. You may need to paste in your API token, which is stored in ~/.pypirc or your PyPI account settings.

Troubleshooting

Issues authenticating when uploading to PyPI from Terminal

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

[distutils]
index-servers =
    pypi

[pypi]
repository: https://pypi.python.org/pypi
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