Guide · Open source

How to use Poetry: install, manage dependencies and build packages

Q: Is Poetry free to use?

Poetry is released under the MIT licence, according to the project's repository details. The MIT licence is a permissive open-source licence, so check its terms if you plan to redistribute it.

Q: What do I need to install Poetry?

You need Python installed. The README's example uses requires-python >=3.9 for a package, but it does not state the Poetry version's own Python requirement, so check the installation documentation.

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Poetry is an open-source Python tool that helps you declare the libraries your project needs, lock their exact versions, and install them the same way on other machines. It also builds and publishes Python packages. This guide covers installing Poetry, setting up a pyproject.toml file, using dependency groups, and deciding whether it fits your project.

Poetrypython-poetry/poetry · ★ 34.3k · MIT Install options & downloads

Quick start

1Install Poetry. Run the official install script from install.python-poetry.org with Python available on your system.
2Create or convert pyproject.toml. Put your project metadata, dependencies and Python requirement in one pyproject.toml file, replacing setup.py and requirements.txt.
3Declare dependencies. List packages with version ranges in the dependencies section, and add extras or dependency groups such as dev, docs or lint where needed.
4Install the project. Run poetry install to install your declared dependencies, adding --with docs or -E my-extra for optional groups or extras.
5Share the lock file. Commit the lock file so every machine and CI run installs the same resolved versions.
6Build the package. Use Poetry's build backend to build a Python package from pyproject.toml when you are ready to distribute it.

Install Poetry with the official script

Poetry supports several installation methods. The simplest one shown in the project README is the official install script, which you run from a terminal. Its prerequisite is Python. The README does not state the exact Poetry version requirement, so check the full installation documentation before you install.

For full instructions, including advanced script usage, alternate install methods and CI best practices, use the installation documentation linked from the project's website.

curl -sSL https://install.python-poetry.org | python3 -

Understand the pyproject.toml file

Poetry uses a single pyproject.toml file in place of several older project files. According to the README, it replaces setup.py, requirements.txt, setup.cfg, MANIFEST.in and Pipfile with one simple project format.

The file has a [project] section for package metadata and dependencies, and a [tool.poetry.dependencies] section where Poetry sets its Python upper bound for locking. The README example uses python = ">=3.9,<4.0" in that section and requires-python = ">=3.9" in the package metadata.

[build-system] names poetry-core and the poetry.core.masonry.api build backend.
[project] holds name, version, description, readme, license and authors.
dependencies lists packages with version ranges, such as "requests[security] (>=2.28,<3.0)".
[project.scripts] maps a command name to a function, for example my_package_cli = "my_package.console:run".

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

[project]
name = "my-package"
version = "0.1.0"
description = "The description of the package"
readme = "README.md"
license = "MIT"
license-files = ["LICENSE"]
requires-python = ">=3.9"

dependencies = [
    "aiohttp (>=3.8.1,<4.0.0)",
    "requests[security] (>=2.28,<3.0)",
]

Add optional dependency groups

Poetry supports dependency groups for organizing packages such as test, documentation or lint tools. The README shows dev and docs groups under [dependency-groups]. Groups can be marked optional so they install only when you ask for them.

The README gives two ways to install an optional group or extra: poetry install --with docs for groups, and poetry install -E my-extra for an optional dependency defined under [project.optional-dependencies].

dev: pytest and pytest-cov, in the README example.
docs: Sphinx, marked optional so it is skipped by default.
lint: ruff, defined with the Poetry-specific [tool.poetry.group.lint.dependencies] syntax.

poetry install --with docs

Install the same versions on every machine

Poetry is designed to lock exact dependency versions and install them consistently on other machines. This matters for teams and for continuous integration (CI), where you want the same stack everywhere. The README states the goal as ensuring you have the right stack everywhere, and the install documentation covers CI best practices.

Poetry records resolved versions in a lock file. Commit it to version control so teammates and CI install the same packages.

Build and publish a package

If you maintain a Python library, Poetry can build packages from your pyproject.toml file and publish them. The build backend is poetry-core, which the README describes as a PEP 517 build system for Poetry projects.

The README also lists related projects: poetry-plugin-export for exporting to formats such as requirements.txt, and poetry-plugin-bundle for installing to formats such as virtual environments.

What people use it for

Starting a new Python project with one config file for dependencies and packaging.
Keeping the same dependency versions on a laptop, a teammate's machine and CI.
Organizing test, documentation and lint tools into separate optional dependency groups.
Building and publishing a Python library from pyproject.toml.

Frequently asked questions

Is Poetry free to use?

Poetry is released under the MIT licence, according to the project's repository details. The MIT licence is a permissive open-source licence, so check its terms if you plan to redistribute it.

What do I need to install Poetry?

You need Python installed. The README's example uses requires-python >=3.9 for a package, but it does not state the Poetry version's own Python requirement, so check the installation documentation.

How do I install Poetry?

The README shows the official script: curl -sSL https://install.python-poetry.org | python3 -. The README also points to the full installation documentation for alternate methods and CI use.

Does Poetry replace requirements.txt and setup.py?

Yes. The README says Poetry replaces setup.py, requirements.txt, setup.cfg, MANIFEST.in and Pipfile with a single pyproject.toml file. Migrating an existing project takes some effort.

What are the alternatives to Poetry?

The project lists pip-tools, PDM, Pipenv and uv as comparable projects. Choose based on whether you need locking, packaging, or only a simple script runner.

Is Poetry only for Python projects?

Yes. The tool is specific to the Python ecosystem, so it is not suited to non-Python projects.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Poetry suits Python developers starting a new project who want one pyproject.toml for dependencies and packaging, and teams that need identical installs in CI. If you only run a single script, or your project must stay on setup.py or requirements.txt, the setup and migration cost may not be worth it, and simpler tools in the same space may fit better.

Install options & downloads