Specifying your dependencies with Poetry¶

Declaring your project metadata¶

Poetry is a PEP 517-compliant build backend, which means that it can generate your project metadata using a standardized interface that can be consumed directly by pip. To do that, first make sure that the build-system section of your pyproject.toml declares the build backend as follows:

pyproject.toml¶

[build-system]
requires = ["poetry_core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

Then, you will be able to install it on Read the Docs just using pip, with a configuration like this:

.readthedocs.yaml¶

version: 2

build:
  os: ubuntu-20.04
  tools:
    python: "3.9"

python:
  install:
    - method: pip
      path: .

For example, the rich Python library uses Poetry to declare its library dependencies and installs itself on Read the Docs with pip.

Locking your dependencies¶

With your pyproject.toml file you are free to specify the dependency versions that are most appropriate for your project, either by leaving them unpinned or setting some constraints. However, to achieve Reproducible Builds it is better that you lock your dependencies, so that the decision to upgrade any of them is yours. Poetry does this using poetry.lock files that contain the exact versions of all your transitive dependencies (that is, all the dependencies of your dependencies).

The first time you run poetry install in your project directory Poetry will generate a new poetry.lock file with the versions available at that moment. You can then commit your poetry.lock to version control so that Read the Docs also uses these exact dependencies.