Backstory Recently, I decided to create my first Python package and publish it to PyPI. After a month of writing and testing code, I finally prepared everything for publication. Because this was new for me, I encountered several pitfalls along the way, so I decided to share the steps on how you can do the same. You can check my package on GitHub or Pypi. Note: In this article, I will discuss how to create and prepare a package for publication using Poetry. Poetry automates many tasks for you. If you prefer to manually prepare the package, you can refer to the guide. Prepare an Account on PyPi First things first. You need an account. Go to https://pypi.org/ to create the account and finish its setup. Generate an API Token on PyPi To publish a package on PyPI, you will need to generate a token for your account. Once you are registered on PyPI, go to your account page, scroll down to the API tokens section, and click the Generate API token button. Choose a name and the scope for the token. If you don't have any projects on PyPI, you will only be able to create an account-scoped API token, which will be used to publish new packages. Save the API token. We will need it later. Prepare a Project First, create a folder where the package files will be stored. Next, create a Python virtual environment. I prefer to create the virtual environment in the project's folder, but poetry provides the option to create it in {cache-dir}/virtualenvs. python3 -m venv .venv

source .venv/bin/activate After creating the virtual environment, we need to install and initialize poetry. pip install poetry

poetry init Poetry will ask you to set several settings during the initialization, which you can change later manually. As a result, a file called pyproject.toml will be generated. This is the most important file, responsible for the project's operation and dependency management. It should look something like this: [tool.poetry]
name = "pypi-poetry-publish-example"
version = "0.1.0"
description = ""
authors = ["Author <email@email.com>"]
readme = "README.md"
packages = [{include = "pypi_poetry_publish_example"}]

[tool.poetry.dependencies]
python = "^3.10"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api" Let's explain some fields in the file: name - is the name of the project. By default, it is the name of the folder where poetry was initialized. version - project's version. It will be used for versioning when the package will be published. python - python version required for the project. build-system - the system that is used for building source distributions or wheels from them. readme - a filename that will be used for package description. If it is set here, you need to create it in the root. After we have prepared poetry, we will create a new folder called pypi_poetry_publish_example where package files will be stored. Inside the folder, we will create a file core.py. Important: The name of the folder where the package files are stored should be the same as the name set in pyproject.toml, written in camel case. In our case: pypi-poetry-publish-example(pyproject.toml) -> pypi_poetry_publish_example (folder name) # core.py
PREPEND_STR = 'prepend_'

def modify_str(string: str) -> str:
    return f'{PREPEND_STR}{string}' Additionally, it is a good idea to add a LICENSE file. The MIT license is commonly used. Finally, we need to save what versions of packages have been installed: poetry lock As a result, the project structure should look like this: pypi-poetry-publish-example/
├── LICENSE
├── poetry.lock
├── pyproject.toml
├── README.md
├── pypi_poetry_publish_example/
       ├── __init__.py
       └── core.py Build and Publish the Package Our project is ready to be published, but before that, we need to build the source and wheel archives. To do this, we use the following command: poetry build Before we publish the package, we need to set the API token: poetry config pypi-token.pypi pypi-XXXXXXXX where pypi-XXXXXXXX is the API token generated in your account. This will create the required files to be published; to upload them to Pypi, use: poetry publish Congratulations! Your package has been uploaded, and it can be verified by visiting the projects page. Now, it can be installed using: pip install pypi-poetry-publish-example Extra Dependencies There were no dependencies added in the example. Dependencies can be added using Poetry if needed. After installation, they will be added to tool.poetry.dependencies and will be required by the package. You might have seen commands like pip install somepackage[extra]. This parameter will install the extra optional features which won't be automatically added if only the command pip install somepackage is applied. To do this in your project, you need to add the optional flag to the dependency you want to make optional, and add it to [tool.poetry.extras].  The pyproject.toml with the optional package pydantic will look like this: [tool.poetry]
name = "pypi-poetry-publish-example"
version = "0.1.0"
description = ""
authors = ["Author <email@email.com>"]
readme = "README.md"
packages = [{include = "pypi_poetry_publish_example"}]

[tool.poetry.dependencies]
python = "^3.10"
pydantic = {version=">=1.9", optional = true}

[tool.poetry.extras]
pydantic = ["pydantic"]

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api" Backstory Recently, I decided to create my first Python package and publish it to PyPI. After a month of writing and testing code, I finally prepared everything for publication. Because this was new for me, I encountered several pitfalls along the way, so I decided to share the steps on how you can do the same. You can check my package on GitHub or Pypi . GitHub Pypi Note : In this article, I will discuss how to create and prepare a package for publication using Poetry. Poetry automates many tasks for you. If you prefer to manually prepare the package, you can refer to the guide . Note guide Prepare an Account on PyPi First things first. You need an account. Go to https://pypi.org/ to create the account and finish its setup. https://pypi.org/ Generate an API Token on PyPi To publish a package on PyPI, you will need to generate a token for your account. Once you are registered on PyPI, go to your account page , scroll down to the API tokens section, and click the Generate API token button. Choose a name and the scope for the token. account page Generate API token If you don't have any projects on PyPI, you will only be able to create an account-scoped API token, which will be used to publish new packages. Save the API token. We will need it later. Prepare a Project First, create a folder where the package files will be stored. Next, create a Python virtual environment. I prefer to create the virtual environment in the project's folder, but poetry provides the option to create it in {cache-dir}/virtualenvs . poetry {cache-dir}/virtualenvs python3 -m venv .venv

source .venv/bin/activate python3 -m venv .venv

source .venv/bin/activate After creating the virtual environment, we need to install and initialize poetry . poetry pip install poetry

poetry init pip install poetry

poetry init Poetry will ask you to set several settings during the initialization, which you can change later manually. As a result, a file called pyproject.toml will be generated. Poetry pyproject.toml This is the most important file, responsible for the project's operation and dependency management. It should look something like this: [tool.poetry]
name = "pypi-poetry-publish-example"
version = "0.1.0"
description = ""
authors = ["Author <email@email.com>"]
readme = "README.md"
packages = [{include = "pypi_poetry_publish_example"}]

[tool.poetry.dependencies]
python = "^3.10"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api" [tool.poetry]
name = "pypi-poetry-publish-example"
version = "0.1.0"
description = ""
authors = ["Author <email@email.com>"]
readme = "README.md"
packages = [{include = "pypi_poetry_publish_example"}]

[tool.poetry.dependencies]
python = "^3.10"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api" Let's explain some fields in the file: name - is the name of the project. By default, it is the name of the folder where poetry was initialized. name - is the name of the project. By default, it is the name of the folder where poetry was initialized. name version - project's version. It will be used for versioning when the package will be published. version - project's version. It will be used for versioning when the package will be published. version python - python version required for the project. python - python version required for the project. python build-system - the system that is used for building source distributions or wheels from them. build-system - the system that is used for building source distributions or wheels from them. build-system readme - a filename that will be used for package description. If it is set here, you need to create it in the root. readme - a filename that will be used for package description. If it is set here, you need to create it in the root. readme After we have prepared poetry, we will create a new folder called pypi_poetry_publish_example where package files will be stored. Inside the folder, we will create a file core.py . poetry, pypi_poetry_publish_example core.py Important : The name of the folder where the package files are stored should be the same as the name set in pyproject.toml , written in camel case. Important pyproject.toml In our case: pypi-poetry-publish-example ( pyproject.toml ) -> pypi_poetry_publish_example ( folder name ) pypi-poetry-publish-example pyproject.toml pypi_poetry_publish_example folder name # core.py
PREPEND_STR = 'prepend_'

def modify_str(string: str) -> str:
    return f'{PREPEND_STR}{string}' # core.py
PREPEND_STR = 'prepend_'

def modify_str(string: str) -> str:
    return f'{PREPEND_STR}{string}' Additionally, it is a good idea to add a LICENSE file. The MIT license is commonly used. LICENSE Finally, we need to save what versions of packages have been installed: poetry lock poetry lock As a result, the project structure should look like this: pypi-poetry-publish-example/
├── LICENSE
├── poetry.lock
├── pyproject.toml
├── README.md
├── pypi_poetry_publish_example/
       ├── __init__.py
       └── core.py pypi-poetry-publish-example/
├── LICENSE
├── poetry.lock
├── pyproject.toml
├── README.md
├── pypi_poetry_publish_example/
       ├── __init__.py
       └── core.py Build and Publish the Package Our project is ready to be published, but before that, we need to build the source and wheel archives. To do this, we use the following command: poetry build poetry build Before we publish the package, we need to set the API token: poetry config pypi-token.pypi pypi-XXXXXXXX poetry config pypi-token.pypi pypi-XXXXXXXX where pypi-XXXXXXXX is the API token generated in your account. pypi-XXXXXXXX This will create the required files to be published; to upload them to Pypi, use: poetry publish poetry publish Congratulations! Your package has been uploaded, and it can be verified by visiting the projects page . projects page Now, it can be installed using: pip install pypi-poetry-publish-example pip install pypi-poetry-publish-example Extra Dependencies There were no dependencies added in the example. Dependencies can be added using Poetry if needed. After installation, they will be added to tool.poetry.dependencies and will be required by the package. tool.poetry.dependencies You might have seen commands like pip install somepackage[extra] . This parameter will install the extra optional features which won't be automatically added if only the command pip install somepackage is applied. pip install somepackage[extra] extra pip install somepackage To do this in your project, you need to add the optional flag to the dependency you want to make optional, and add it to [tool.poetry.extras] .  The pyproject.toml with the optional package pydantic will look like this: optional [tool.poetry.extras] pyproject.toml pydantic [tool.poetry]
name = "pypi-poetry-publish-example"
version = "0.1.0"
description = ""
authors = ["Author <email@email.com>"]
readme = "README.md"
packages = [{include = "pypi_poetry_publish_example"}]

[tool.poetry.dependencies]
python = "^3.10"
pydantic = {version=">=1.9", optional = true}

[tool.poetry.extras]
pydantic = ["pydantic"]

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api" [tool.poetry]
name = "pypi-poetry-publish-example"
version = "0.1.0"
description = ""
authors = ["Author <email@email.com>"]
readme = "README.md"
packages = [{include = "pypi_poetry_publish_example"}]

[tool.poetry.dependencies]
python = "^3.10"
pydantic = {version=">=1.9", optional = true}

[tool.poetry.extras]
pydantic = ["pydantic"]

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

How to Set Up GitHub Actions and PyPI Integration for Python Projects

Read My Stories

Too Long; Didn't Read

Make resilience your competitive advantage

Step-by-Step Guide to Publishing Your First Python Package on PyPI Using Poetry: Lessons Learned

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

Philosophy of Testing and Rules How to Reliably Test Complex Applications With Python Examples

Choosing the Right Package Manager: NPM, Yarn, or PNPM?

Debian Package Management

How to Decide Which Packages to Use

How To Find And Fix Broken Packages On Linux

Philosophy of Testing and Rules How to Reliably Test Complex Applications With Python Examples

Choosing the Right Package Manager: NPM, Yarn, or PNPM?

Debian Package Management

How to Decide Which Packages to Use

How To Find And Fix Broken Packages On Linux

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps