Documentation

Introduction

Poetry is a tool for dependency management and packaging in Python.

Basic usage

For the basic usage introduction we will be installing pendulum, a datetime library.

Managing dependencies

Poetry supports specifying main dependencies in the project.dependencies section of your pyproject.toml according to PEP 621.

Libraries

This chapter will tell you how to make your library installable through Poetry. Versioning Poetry requires PEP 440-compliant versions for all projects. While Poetry does not enforce any release convention, it used to encourage the use of semantic versioning within the scope of PEP 440 and supports version constraints that are especially suitable for semver. Note As an example, 1.0.0-hotfix.1 is not compatible with PEP 440.

Commands

You’ve already learned how to use the command-line interface to do some things.

Configuration

Poetry can be configured via the config command (see more about its usage here) or directly in the config.toml file that will be automatically created when you first run that command.

Repositories

Poetry supports the use of PyPI and private repositories for discovery of packages as well as for publishing your projects. By default, Poetry is configured to use the PyPI repository, for package installation and publishing. So, when you add dependencies to your project, Poetry will assume they are available on PyPI. This represents most cases and will likely be enough for most users. Private Repository Example Installing from private package sources By default, Poetry discovers and installs packages from PyPI.

Managing environments

Poetry makes project environment isolation one of its core features. What this means is that it will always work isolated from your global Python installation.

Dependency specification

Dependencies for a project can be specified in various forms, which depend on the type of the dependency and on the optional constraints that might be needed for it to be installed. project.dependencies and tool.poetry.dependencies Prior Poetry 2.0, dependencies had to be declared in the tool.poetry.dependencies section of the pyproject.toml file. [tool.poetry.dependencies] requests = "^2.13.0" With Poetry 2.0, you should consider using the project.dependencies section instead. [project] # ...

Plugins

Poetry supports using and building plugins if you wish to alter or expand Poetry’s functionality with your own. For example if your environment poses special requirements on the behaviour of Poetry which do not apply to the majority of its users or if you wish to accomplish something with Poetry in a way that is not desired by most users. In these cases you could consider creating a plugin to handle your specific logic. .

The pyproject.toml file

In package mode, the only required fields are name and version (either in the project section or in the tool.poetry section).

Contributing to Poetry

First off, thanks for taking the time to contribute! The following is a set of guidelines for contributing to Poetry on GitHub.

Community

Badge For any projects using Poetry, you may add its official badge somewhere prominent like the README. Markdown [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/) reStructuredText ..

FAQ

Why is the dependency resolution process slow? While the dependency resolver at the heart of Poetry is highly optimized and should be fast enough for most cases, with certain sets of dependencies, it can take time to find a valid solution. This is due to the fact that not all libraries on PyPI have properly declared their metadata and, as such, they are not available via the PyPI JSON API.

pre-commit hooks

pre-commit is a framework for building and running git hooks.

Building extension modules

Building Extension Modules Warning While this feature has been around since almost the beginning of the Poetry project and has needed minimal changes, it is still considered unstable.

2.5 Stable Documentation for the latest, stable, branch. main Development Documentation for the latest, in-development, branch.
Blog
History

Documentation Blog History

Releases

Published on September 19, 2026 in with tags

Footer

Python packaging and dependency management made easy.

GitHub Discord

Documentation

Introduction
Basic usage
Managing dependencies
Libraries
Commands
Configuration
Repositories
Managing environments
Dependency specification
Plugins
The pyproject.toml file
Contributing to Poetry
Community
FAQ
pre-commit hooks
Building extension modules

Github

Project
Issues
Discussions

Other Projects

poetry-core
install.python-poetry.org
Bundle plugin
Export plugin