How To Use Poetry to Publish a Python Package on PyPI

Using Poetry to manage Python dependencies and virtual environments is much easier than the traditional requirements.txt and other tools. When you want to release your package and make it available on PyPI, Poetry also lets you avoid the need to use the standard Python setuptools setup.cfg or setup.py files, so it's much simpler and less confusing. If you'd like a brief introduction to Poetry, I'd recommend this article: Five Minute Introduction: Poetry.

When I released my first PyPI package, Randalyze, I had some problems finding practical instructions on how to use Poetry to handle the configuration and release process. In case you're having the same problems, here's how I did it.

The Steps You Need To Take

Install Poetry on your development machine. If you're using PyCharm, support for Poetry is built in.

You'll need to start with a Python project that uses Poetry, and has a valid pyproject.toml file. If your project doesn't use Poetry yet, use the poetry init command to fix that. Open the pyproject.toml file, and make sure that the following fields are populated:

In the [tool.poetry] section, make sure that the following values are populated:

[tool.poetry]
name
version
description
keywords
authors
readme
license
classifiers

If you have an article or web site about the package, add an entry or two in the [tool.poetry.urls] section.

Once you've done this, create accounts on each of the following sites:

• Test PyPI - This is a test version of PyPI where you can experiment with things before you upload to the publically-accessible PyPI.
• PyPI

You might want to use the same user name for both sites, but you don't have to.

Starting with the Test PyPI site, once you've created your account, you're going to need to go to the Account Settings page and create an API Token. The token needs a scope of "All projects". Once it's been generated (it's in the format pypi-xxxxxxxx), keep it on the the screen - you're going to need it soon.

Now open a terminal in the directory containing your project, or open a Terminal window in PyCharm. Set up a repository for testpypi using the following commands:

poetry config repositories.testpypi https://test.pypi.org/legacy/

poetry config pypi-token.testpypi <API Token>

To make sure that the configuration is correct, use the dry run feature to test it:

poetry publish -r testpypi --build --dry-run

The output of this command should describe the process of building and then publishing your package. It will say that it's publishing the files but don't worry, the --dry-run option prevents it from actually doing anything.

Once you've got this working, you can delete the --dry-run option and run the command again to make sure everything gets built and uploaded. The command you need is:

poetry publish -r testpypi --build

Once this has run successfully, go to your account page on test.pypi.org. Click on the Manage button, and you should see that your project has uploaded correctly. Note that if you want to upload it again, you'll need to update the version number in the pyproject.toml file.

Now that you've successfully uploaded your package to the test version of PyPI, it's time to do the same to the real PyPI, so that people can actually download it and use it.

Log into your PyPI account and, as with the test PyPI site, create an API Token with "All Projects" access and leave it on the screen. From the terminal window you used before, or PyCharm's terminal window, configure Poetry to add PyPI as an option using the following commands:

poetry config pypi-token.pypi <API Token>i

You don't need to add PyPI as a repository, as it's Poetry's default. You need to add your API Token though. Run the next command to run a dry run against PyPI - if you don't specify a repository then Poetry assumes you want to use PyPI:

poetry publish --build --dry-run

Again, you should see everything build, unless you haven't changed anything, and then the publishing messages that aren't actually doing anything. To perform a real build and upload, run:

poetry publish --build

Go to your account page on PyPI at https://pypi.org/manage/projects/ and check to ensure your package has uploaded. Once your package is in PyPI, people can download it using pip, so now is a good time to publicize it!

Every time you update your package, all you need to do now is to increase the version number and run:

poetry publish --build

to update PyPI with the latest version