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.

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.