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/

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.

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. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request. How to contribute Reporting bugs This section guides you through submitting a bug report for Poetry. Following these guidelines helps maintainers and the community understands your report, reproduces the behavior, and finds related reports.

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. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request. How to contribute Reporting bugs This section guides you through submitting a bug report for Poetry. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.

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).

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.

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] # ... dependencies = [ "requests (>=2.23.0,<3.0.0)" ] While dependencies in tool.poetry.dependencies are specified using toml tables, dependencies in project.dependencies are specified as strings according to PEP 508.

Basic usage For the basic usage introduction we will be installing pendulum, a datetime library. If you have not yet installed Poetry, refer to the Introduction chapter. Project setup First, let’s create our new project, let’s call it poetry-demo: poetry new poetry-demo This will create the poetry-demo directory with the following content: poetry-demo ├── pyproject.toml ├── README.md ├── poetry_demo │ └── __init__.py └── tests └── __init__.py The pyproject.toml file is what is the most important here. This will orchestrate your project and its dependencies. For now, it looks like this:

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.0.0-post1 or 1.0.0.post1. Lock file For your library, you may commit the poetry.lock file if you want to. This can help your team to always test against the same dependency versions. However, this lock file will not have any effect on other projects that depend on it. It only has an effect on the main project.

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.