Skip to content

Poetry

Dependency management, virtual environments and publishing behind one command.

Developer UtilitiesCLI/UtilsPython
Official docs ↗GitHub ↗

What it is

Poetry is a Python dependency management and packaging tool that simplifies the process of managing project dependencies, building packages, and publishing them. It ensures deterministic installs and isolated environments.

Poetry provides commands to create new projects, add or remove dependencies, build and publish packages, and manage virtual environments automatically. It uses a `pyproject.toml` file to track project metadata and dependencies.

Licence
MIT
Best known for
Making Python packaging coherent before the standards caught up

When to use it

The question documentation cannot answer for you — because it cannot recommend something else.

Reach for it when

  • Publishing a library to PyPI, where its build and version handling shine
  • You want a lockfile and reproducible installs without assembling the tooling yourself

Look elsewhere when

  • You want maximum speed and standards-plain configuration — uv has largely taken this ground
  • The project is a single script with two dependencies

Installation

pip install poetry

Getting started

The smallest useful thing you can do with it, and what each part means.

Creating a new project
poetry new my-project
Creates a new Python project named 'my-project' with a standard directory structure and a `pyproject.toml` file.
Adding dependencies
poetry add requests
Adds the `requests` library to the project and updates the `pyproject.toml` and `poetry.lock` files.
Installing dependencies
poetry install
Installs all dependencies listed in `pyproject.toml` into a virtual environment managed by Poetry.

Advanced usage

Where the library earns its place over a simpler alternative.

Removing a dependency
poetry remove requests
Removes the `requests` dependency from the project and updates the lock file.
Running commands inside the virtual environment
poetry run python script.py
Executes a Python script using the virtual environment managed by Poetry.
Publishing a package
poetry publish --build
Builds the project package and publishes it to PyPI.
Checking dependency status
poetry show --tree
Displays a tree of all project dependencies and their versions.

Errors and fixes

The failures you are most likely to hit, and what actually resolves them.

PackageNotFoundError
Verify the package name and check PyPI availability before adding it.
CommandNotFoundError
Ensure Poetry is installed correctly and is available in your system PATH.
VersionConflict
Resolve conflicting dependency versions manually or use `poetry update`.

Best practices

  • Use `poetry.lock` to ensure deterministic installs across different environments.
  • Keep development dependencies separate from production dependencies using `--dev` flag.
  • Regularly update dependencies using `poetry update` to maintain security and compatibility.
  • Use `poetry check` to verify the integrity of your `pyproject.toml` file.
  • Leverage virtual environments managed by Poetry instead of system-wide installations.

Alternatives

Comparable options, and the reason you would pick one over the other.

  • uv

    Dramatically faster, speaks standard pyproject.toml; the emerging default

Background

Why it exists, and what it was reacting to.

Poetry was created by Sébastien Eustace in 2018 to provide a modern alternative to pip and setuptools for Python projects. It emphasizes simplicity, reproducibility, and a standardized approach to dependency management, making Python project setups more predictable and reliable.

Related libraries

Others in Developer Utilities for Python.

← All Python librariesPython guide