Managing dependencies Poetry supports specifying main dependencies in the project.dependencies section of your pyproject.toml according to PEP 621. For legacy reasons and to define additional information that are only used by Poetry the tool.poetry.dependencies sections can be used. See Dependency specification for more information. Dependency groups Poetry provides a way to organize your dependencies by groups. The dependencies declared in project.dependencies respectively tool.poetry.dependencies are part of an implicit main group. Those dependencies are required by your project during runtime.

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. To achieve this, it will first check if it’s currently running inside a virtual environment. If it is, it will use it directly without creating a new one. But if it’s not, it will use one that it has already created or create a brand new one for you.

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

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.

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. Optional See basic usage for more information. package-mode = false name The name of the package. Required in package mode This should be a valid name as defined by PEP 508. name = "my-package" version The version of the package. Required in package mode This should be a valid PEP 440 string.

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). Other fields are optional. In non-package mode, the name and version fields are required if using the project section. Note Run poetry check to print warnings about deprecated fields. The project section The project section of the pyproject.toml file according to the specification of the PyPA. name The name of the package. Always required when the project section is specified

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. But, you want to install a dependency to your project for a simple API repository? Let’s do it.

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", "./subdirectory"]. poetry-check The poetry-check hook calls the poetry check command to make sure the poetry configuration does not get committed in a broken state.

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

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. You can participate in the discussions about stabilizing this feature here. And as always, your contributions towards the goal of improving this feature are also welcome. Poetry allows a project developer to introduce support for, build and distribute native extensions within their project. In order to achieve this, at the highest level, the following steps are required.