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. This file can typically be found in one of the following directories: macOS: ~/Library/Application Support/pypoetry Windows: %APPDATA%\pypoetry For Unix, we follow the XDG spec and support $XDG_CONFIG_HOME. That means, by default ~/.config/pypoetry. Local configuration Poetry also provides the ability to have settings that are specific to a project by passing the --local option to the config command.

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. See the official documentation for more information: pre-commit.com This document provides a list of available pre-commit hooks provided by Poetry. Note If you specify the args: for a hook in your .pre-commit-config.yaml, the defaults are overwritten. You must fully specify all arguments for your hook if you make use of args:. Note If the pyproject.toml file is not in the root directory, you can specify args: ["-C", ".

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. An update is allowed if the new version number does not modify the left-most non-zero digit in the major, minor, patch grouping. For instance, if we previously ran poetry add requests@^2.

pre-commit hooks pre-commit is a framework for building and running git hooks. See the official documentation for more information: pre-commit.com This document provides a list of available pre-commit hooks provided by Poetry. Note If you specify the args: for a hook in your .pre-commit-config.yaml, the defaults are overwritten. You must fully specify all arguments for your hook if you make use of args:. Note If the pyproject.toml file is not in the root directory, you can specify args: ["-C", ".

Introduction Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution. System requirements Poetry requires Python 3.8+. It is multi-platform and the goal is to make it work equally well on Linux, macOS and Windows.

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. You can instead choose to use 1.

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. You can instead choose to use 1.

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.

Managing dependencies Dependency groups Poetry provides a way to organize your dependencies by groups. For instance, you might have dependencies that are only needed to test your project or to build the documentation. To declare a new dependency group, use a tool.poetry.group.<group> section where <group> is the name of your dependency group (for instance, test): [tool.poetry.group.test] # This part can be left out [tool.poetry.group.test.dependencies] pytest = "^6.0.0" pytest-mock = "*" Note All dependencies must be compatible with each other across groups since they will be resolved regardless of whether they are required for installation or not (see Installing group dependencies).