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

Dependency groups Poetry provides a way to organize your dependencies by groups.

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. Version constraints Caret requirements Caret requirements allow SemVer compatible updates to a specified version.

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

The tool.poetry section of the pyproject.toml file is composed of multiple sections. package-mode Whether Poetry operates in package mode (default) or not.

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.

1.8 Stable Documentation for the latest, stable, branch. master Development Documentation for the latest, in-development, branch.
Blog
History

Documentation Blog History

Announcing Poetry 1.8.0

Published on February 25, 2024 in Releases with tags 1.X 1.8

The Poetry team is pleased to announce the immediate availability of Poetry 1.8.0.

Footer

Python packaging and dependency management made easy.

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

Github

Project
Issues
Discussions

Other Projects

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

Copyright © 2018-2024. All Rights Reserved. Powered by