Release your Python package

package
release
python
pypi
testpypi
Last reviewed

April 4, 2025

Last modified

May 13, 2025

After bundling your source code into a package, you can publish it to PyPI. This will allow others to easily install your package using pip.

Testing packaging on TestPyPI before publishing to PyPI

By testing your package on TestPyPI before publishing it to PyPI, you can identify and address any issues with your package metadata, dependencies, or distribution files before making your package publicly available.

You’ll need to create an account for TestPyPI. The next step is to create distribution packages for your package. These packages are archives that can be uploaded to TestPyPI/PyPI and installed using pip. Then you can use Twine to upload your package to TestPyPI.

  1. Register on TestPyPI.

  2. Check if PyPA build is installed:

    pip install --upgrade build

  3. To create distribution packages, navigate to the directory where your pyproject.toml file is located, and run:

python3 -m build
py -m build
Output

After running this command, you’ll see a substantial amount of text output. Upon completion, it will generate two files (a wheel and .tar.gz file) in the dist/ directory. The .tar.gz file represents a source distribution, while the .whl file is a built distribution. More recent versions of pip prioritize the installation of built distributions, reverting to source distributions if necessary. It’s advisable to always upload a source distribution and include built distributions compatible with the platforms your project supports.

  1. Then, install Twine:

    pip install twine

  2. Upload to TestPyPI by specifying the --repository flag:

    twine upload --repository testpypi dist/*
    • You will be prompted to enter your username and password for TestPyPI.
    • If you have a ~/.pypirc file, Twine will use the credentials from there.

  3. You will find your package on https://test.pypi.org/project/your_pkg_name. You can then pip install it by adding the --index-url flag:

    pip install --index-url https://test.pypi.org/simple/your_pkg_name

Publishing to PyPI

Once you have tested your package on TestPyPI and ensured everything works as expected, you can publish it to the official PyPI repository. It will be accessible to anyone in the Python community, allowing them to install your package using a simple pip install your_pkg_name command.

You’ll also need an account for PyPI. TestPyPI and PyPI use separate databases so you need to register on both sites. However, the workflow is about the same:

  1. Register on PyPI.
  2. Run pip install --upgrade build to ensure you have the latest version of the build tool.
  3. Navigate to the directory where your pyproject.toml file is located, and run:
python3 -m build
py -m build

  1. Upload your package to PyPI:

    twine upload dist/*
    • Input your credentials associated with the account you registered on the official PyPI platform.

  2. Your package is live on PyPI!

  3. You can now install it by simply pip install your_pkg_name.

Tip

If you need a particular name for your package, check whether it is taken on PyPI and claim it as soon as possible if available.

Learn more