How To Publish Python Packages to PyPI using Poetry on Ubuntu 22.04

Published on October 20, 2022
How To Publish Python Packages to PyPI using Poetry on Ubuntu 22.04


Poetry is a dependency manager for Python that is also capable of building and packaging your Python projects for distribution. PyPI is the official Python repository for uploading and downloading Python packages, and will be used in this tutorial. It is the official third party source for Python packages, and is operated by the Python Software Foundation. Publishing your packages on PyPI makes it publicly available for installation by yourself, or anyone else.

In this tutorial you will create a PyPI account, set up token authentication with your account to enable use with Poetry, then build and publish your packaged project onto PyPI. This will also enable you to add your published package as a dependency to your other Python projects.


Step 1 — Creating a PyPI Account

In order to publish a package to PyPI, you will need to create an account. Go to the official registration page in your web browser:

PyPI Signup Page
PyPI Signup Page

Next you will need to enable token authentication in order to safely use your PyPI credentials with Poetry.

Step 2 — Enabling Token Authentication for PyPI

Token authentication is the recommended way to use your PyPI account in the command line. You can use a single, automatically generated token instead of a username and password. Tokens can be added and revoked at any time or granted granular access to parts of your account. This makes them more secure, and avoids the risk of your password being compromised. You will need to create a new API token for your account by navigating to your account settings:

PyPI Account Settings
PyPI Account Settings

Scroll down until you reach the “API tokens” section. Click on “Add API token”:

PyPI Add API Token
PyPI Add API Token

On the following page, you can name your token. This tutorial will name it poetry, but feel free to choose whatever name you’d like:

PyPI API Token Creation
PyPI API Token Creation

Once your token is created, it is important to copy your token because it will only be shown once. This is common practice with API tokens that allow you to make a new one as needed, so make note of your token before proceeding.

PyPI Copy Warning
PyPI Copy Warning

You will now use this token to configure your credentials in Poetry to prepare for publishing. Instead of appending your API token to every command that needs it in Poetry, instead you will do it once using Poetry’s configcommand.

Add your API token to Poetry with this command:

  1. poetry config pypi-token.pypi your-api-token

With your API token added as your credentials, Poetry will notify you that your credentials are stored in a plaintext file. This would be an issue if you were using a traditional username and password for your credentials. Given that tokens can be easily deleted and renewed, while also being randomly generated and unique to a single use case, this makes token storage here a safe trade off for convenience. Alternatively, you can opt to enter your API token manually for each command.

With this, you are ready to build and then publish your project.

Step 3 — Building your Project

Building is the same as packaging your project, and this is a required step before you can publish it. To build your project, enter the following:

poetry build
Building sammy-poetry (0.1.0) - Building sdist - Built sammy-poetry-0.1.0.tar.gz - Building wheel - Built sammy_poetry-0.1.0-py3-none-any.whl

Two files will be outputted. First is the source which is sdist, that outputs to a tar.gz file. Second is the compiled package, which is wheel, that outputs to a .whl file. With these files, you are now ready to publish your Python package to PyPI.

Step 4 — Publishing your Python Package to PyPI

PyPI is the default publishing target for Poetry. With your authentication API token already in place, your publish command will not need to include your credentials again.

To publish your compiled package, enter the following:

poetry publish
Publishing sammy-poetry (0.1.0) to PyPI - Uploading sammy-poetry-0.1.0.tar.gz 100% - Uploading sammy_poetry-0.1.0-py3-none-any.whl 100%

You can now check your published package. Open up your PyPI projects in your browser.

PyPI Your Uploaded Package
PyPI Your Uploaded Package

Your package is published, is publicly available on PyPI, and also available as a dependency through Poetry as well. You can add your own published package as a dependency in your other Python projects.

Note: You can build and publish your package to PyPI in one command by adding the following flag to your publish call:

  1. poetry publish --build

This can be more efficient depending on the maturity of your project and workflow.


In this tutorial, you have used Poetry for its building and publishing ability. You created a PyPI account, set up API Token authentication with Poetry, then compiled your project before publishing it. Your package is available as a dependency publicly, and can even be included as a dependency through Poetry.

Next, you may want to delve more deeply into Python by checking out our How To Code in Python tutorial series.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors
Default avatar
Tony Tran


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
Leave a comment

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel