poetry Documentation

1. Project Overview & Quickstart (python-poetry/poetry)

File: README.md

Poetry: Python packaging and dependency management made easy

Poetry helps you declare, manage and install dependencies of Python projects,
ensuring you have the right stack everywhere.

Poetry replaces setup.py, requirements.txt, setup.cfg, MANIFEST.in and Pipfile with a simple pyproject.toml
based project format.

text

/* Detailed source-code truncated for AI context efficiency. */

Installation

Poetry supports multiple installation methods, including a simple script found at install.python-poetry.org. For full
installation instructions, including advanced usage of the script, alternate install methods, and CI best practices, see
the full installation documentation.

Documentation

Documentation for the current version of Poetry (as well as the development branch and recently out of support
versions) is available from the official website.

Contribute

Poetry is a large, complex project always in need of contributors. For those new to the project, a list of
suggested issues to work on in Poetry and poetry-core is available. The full contributing documentation also
provides helpful guidance.

Resources

poetry-core: PEP 517 build-system for Poetry projects, and
dependency-free core functionality of the Poetry frontend
poetry-plugin-export: Export Poetry projects/lock files to
foreign formats like requirements.txt
poetry-plugin-bundle: Install Poetry projects/lock files to
external formats like virtual environments
install.python-poetry.org: The official Poetry
installation script
website: The official Poetry website and blog

Supporters

Thanks to JetBrains for supporting us with licenses for their tools.

File: docs/_index.md

title: "Introduction"
draft: false
type: docs
layout: "single"

menu:
docs:
weight: 0

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.10+. It is multi-platform and the goal is to make it work equally well
on Linux, macOS and Windows.

Installation

{{% note %}}
If you are viewing documentation for the development branch, you may wish to install a preview or development version of Poetry.
See the advanced installation instructions to use a preview or alternate version of Poetry.
{{% /note %}}

{{< tabs tabTotal="4" tabID1="installing-with-pipx" tabID2="installing-with-the-official-installer" tabID3="installing-manually" tabID4="ci-recommendations" tabName1="With pipx" tabName2="With the official installer" tabName3="Manually (advanced)" tabName4="CI recommendations">}}

pipx is used to install Python CLI applications globally while still isolating them in virtual environments.
pipx will manage upgrades and uninstalls when used to install Poetry.

{{< steps >}}
{{< step >}}
Install pipx

If pipx is not already installed, you can follow any of the options in the
official pipx installation instructions.
Any non-ancient version of pipx will do.

{{< /step >}}
{{< step >}}
Install Poetry

bash

pipx install poetry

{{< /step >}}
{{< step >}}
Install Poetry (advanced)

{{% note %}}
You can skip this step, if you simply want the latest version and already installed Poetry as described in the
previous step. This step details advanced usages of this installation method. For example, installing Poetry from
source, having multiple versions installed at the same time etc.
{{% /note %}}

pipx can install different versions of Poetry, using the same syntax as pip:

bash

pipx install poetry==1.8.4

pipx can also install versions of Poetry in parallel, which allows for easy testing of alternate or prerelease
versions. Each version is given a unique, user-specified suffix, which will be used to create a unique binary name:

bash

pipx install [email protected] poetry==1.8.4
[email protected] --version

bash

pipx install --suffix=@preview --pip-args=--pre poetry
poetry@preview --version

Finally, pipx can install any valid pip requirement spec, which
allows for installations of the development version from git, or even for local testing of pull requests:

bash

pipx install --suffix @main git+https://github.com/python-poetry/poetry.git@main
pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head

{{< /step >}}
{{< step >}}
Update Poetry

bash

pipx upgrade poetry

{{< /step >}}
{{< step >}}
Uninstall Poetry

bash

pipx uninstall poetry

We provide a custom installer that will install Poetry in a new virtual environment
and allows Poetry to manage its own environment.

{{< steps >}}
{{< step >}}
Install Poetry

The installer script is available directly at install.python-poetry.org,
and is developed in its own repository.
The script can be executed directly (i.e. 'curl python') or downloaded and then executed from disk
(e.g. in a CI environment).

Linux, macOS, Windows (WSL)

bash

curl -sSL https://install.python-poetry.org | python3 -

Windows (Powershell)

powershell

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

{{% note %}}
If you have installed Python through the Microsoft Store, replace py with python in the command
above.
{{% /note %}}

{{< /step >}}
{{< step >}}
Install Poetry (advanced)

{{% note %}}
You can skip this step, if you simply want the latest version and already installed Poetry as described in the
previous step. This step details advanced usages of this installation method. For example, installing Poetry from
source, using a pre-release build, configuring a different installation location etc.
{{% /note %}}

By default, Poetry is installed into a platform and user-specific directory:

~/Library/Application Support/pypoetry on macOS.
~/.local/share/pypoetry on Linux/Unix.
%APPDATA%\pypoetry on Windows.

If you wish to change this, you may define the $POETRY_HOME environment variable:

bash

curl -sSL https://install.python-poetry.org | POETRY_HOME=/etc/poetry python3 -

If you want to install prerelease versions, you can do so by passing the --preview option to the installation script
or by using the $POETRY_PREVIEW environment variable:

bash

curl -sSL https://install.python-poetry.org | python3 - --preview
curl -sSL https://install.python-poetry.org | POETRY_PREVIEW=1 python3 -

Similarly, if you want to install a specific version, you can use --version option or the $POETRY_VERSION
environment variable:

bash

curl -sSL https://install.python-poetry.org | python3 - --version 1.8.4
curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.8.4 python3 -

You can also install Poetry from a git repository by using the --git option:

bash

curl -sSL https://install.python-poetry.org | python3 - --git https://github.com/python-poetry/poetry.git@main

If you want to install different versions of Poetry in parallel, a good approach is the installation with pipx and suffix.

{{< /step >}}
{{< step >}}
Add Poetry to your PATH

The installer creates a poetry wrapper in a well-known, platform-specific directory:

$HOME/.local/bin on Unix.
%APPDATA%\Python\Scripts on Windows.
$POETRY_HOME/bin if $POETRY_HOME is set.

{{% note %}}
If you have installed Python through the Microsoft Store, the poetry binary
will be installed to a different location, for example:

text

%LOCALAPPDATA%\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0
\LocalCache\Roaming\Python\Scripts

Replace 3.12 with your installed Python version and qbz5n2kfra8p0 with your suffix.
{{% /note %}}

If this directory is not present in your $PATH, you can add it in order to invoke Poetry
as poetry.

Alternatively, the full path to the poetry binary can always be used:

~/Library/Application Support/pypoetry/venv/bin/poetry on macOS.
~/.local/share/pypoetry/venv/bin/poetry on Linux/Unix.
%APPDATA%\pypoetry\venv\Scripts\poetry on Windows.
$POETRY_HOME/venv/bin/poetry if $POETRY_HOME is set.

{{< /step >}}
{{< step >}}
Use Poetry

Once Poetry is installed and in your $PATH, you can execute the following:

bash

poetry --version

If you see something like Poetry (version 2.0.0), your installation is ready to use!
{{< /step >}}
{{< step >}}
Update Poetry

Poetry is able to update itself when installed using the official installer.

{{% warning %}}
Especially on Windows, self update may be problematic
so that a re-install with the installer should be preferred.
{{% /warning %}}

bash

poetry self update

If you want to install pre-release versions, you can use the --preview option.

bash

poetry self update --preview

And finally, if you want to install a specific version, you can pass it as an argument
to self update.

bash

poetry self update 1.8.4

{{< /step >}}
{{< step >}}
Uninstall Poetry

If you decide Poetry isn't your thing, you can completely remove it from your system
by running the installer again with the --uninstall option or by setting
the POETRY_UNINSTALL environment variable before executing the installer.

bash

curl -sSL https://install.python-poetry.org | python3 - --uninstall
curl -sSL https://install.python-poetry.org | POETRY_UNINSTALL=1 python3 -

Poetry can be installed manually using pip and the venv module. By doing so you will essentially perform the steps carried
out by the official installer. As this is an advanced installation method, these instructions are Unix-only and omit specific
examples such as installing from git.

The variable $VENV_PATH will be used to indicate the path at which the virtual environment was created.

bash

python3 -m venv $VENV_PATH
$VENV_PATH/bin/pip install -U pip setuptools
$VENV_PATH/bin/pip install poetry

Poetry will be available at $VENV_PATH/bin/poetry and can be invoked directly or symlinked elsewhere.

To uninstall Poetry, simply delete the entire $VENV_PATH directory.

{{< /tab >}}
{{< tab tabID="ci-recommendations" >}}
Unlike development environments, where making use of the latest tools is desirable, in a CI environment reproducibility
should be made the priority. Here are some suggestions for installing Poetry in such an environment.

Version pinning

Whatever method you use, it is highly recommended to explicitly control the version of Poetry used, so that you are able
to upgrade after performing your own validation. Each install method has a different syntax for setting the version that
is used in the following examples.

Using pipx

Just as pipx is a powerful tool for development use, it is equally useful in a CI environment
and should be one of your top choices for use of Poetry in CI.

bash

pipx install poetry==2.0.0

Using install.python-poetry.org

{{% note %}}
The official installer script (install.python-poetry.org) offers a streamlined and
simplified installation of Poetry, sufficient for developer use or for simple pipelines. However, in a CI environment
the other two supported installation methods (pipx and manual) should be seriously considered.
{{% /note %}}

Downloading a copy of the installer script to a place accessible by your CI pipelines (or maintaining a copy of the
repository) is strongly suggested, to ensure your
pipeline's stability and to maintain control over what code is executed.

By default, the installer will install to a user-specific directory. In more complex pipelines that may make accessing
Poetry difficult (especially in cases like multi-stage container builds). It is highly suggested to make use of
$POETRY_HOME when using the official installer in CI, as that way the exact paths can be controlled.

bash

export POETRY_HOME=/opt/poetry
python3 install-poetry.py --version 2.0.0
$POETRY_HOME/bin/poetry --version

Using pip (aka manually)

For maximum control in your CI environment, installation with pip is fully supported and something you should
consider. While this requires more explicit commands and knowledge of Python packaging from you, it in return offers the
best debugging experience, and leaves you subject to the fewest external tools.

bash

export POETRY_HOME=/opt/poetry
python3 -m venv $POETRY_HOME
$POETRY_HOME/bin/pip install poetry==2.0.0
$POETRY_HOME/bin/poetry --version

{{% note %}}
If you install Poetry via pip, ensure you have Poetry installed into an isolated environment that is not the same
as the target environment managed by Poetry. If Poetry and your project are installed into the same environment, Poetry
is likely to upgrade or uninstall its own dependencies (causing hard-to-debug and understand errors).
{{% /note %}}

{{% warning %}}
Poetry should always be installed in a dedicated virtual environment to isolate it from the rest of your system.
Each of the above described installation methods ensures that.
It should in no case be installed in the environment of the project that is to be managed by Poetry.
This ensures that Poetry's own dependencies will not be accidentally upgraded or uninstalled.
In addition, the isolated virtual environment in which poetry is installed should not be activated for running poetry commands.
{{% /warning %}}

Enable tab completion for Bash, Fish, or Zsh

poetry supports generating completion scripts for Bash, Fish, and Zsh.

{{% note %}}
You may need to restart your shell in order for these changes to take effect.
{{% /note %}}

See poetry help completions for full details, but the gist is as simple as using one of the following:

Bash

Auto-loaded (recommended)

bash

poetry completions bash >> ~/.bash_completion

Lazy-loaded

bash

poetry completions bash > ${XDG_DATA_HOME:-~/.local/share}/bash-completion/completions/poetry

Fish

fish

poetry completions fish > ~/.config/fish/completions/poetry.fish

Zsh

zsh

poetry completions zsh > ~/.zfunc/_poetry

You must then add the following lines in your ~/.zshrc, if they do not already exist:

bash

fpath+=~/.zfunc
autoload -Uz compinit && compinit

Oh My Zsh

zsh

mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry

You must then add poetry to your plugins array in ~/.zshrc:

text

plugins(
	poetry
	...
	)

Prezto

zsh

poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry

If completions still don't work, try removing ~/.cache/prezto/zcompcache and starting a new shell.

File: docs/basic-usage.md

title: "Basic usage"
draft: false
type: docs
layout: single

menu:
docs:
weight: 10

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]({{< relref "docs" >}} "Introduction") chapter.

Project setup

First, let's create our new project, let's call it poetry-demo:

bash

poetry new poetry-demo

This will create the poetry-demo directory with the following content:

text

poetry-demo
├── pyproject.toml
├── README.md
├── src
│   └── 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:

toml

[project]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = [
    {name = "Sébastien Eustace", email = "[email protected]"}
]
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
]

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

Poetry assumes your package contains a package with the same name as project.name located in the root of your
project. If this is not the case, populate [tool.poetry.packages]({{< relref "pyproject#packages" >}}) to specify
your packages and their locations.

Similarly, the traditional MANIFEST.in file is replaced by the project.readme, tool.poetry.include, and
tool.poetry.exclude sections. tool.poetry.exclude is additionally implicitly populated by your .gitignore. For
full documentation on the project format, see the [pyproject section]({{< relref "pyproject" >}}) of the documentation.

Setting a Python Version

{{% note %}}
Unlike with other packages, Poetry will not automatically install a python interpreter for you.
If you want to run Python files in your package like a script or application, you must bring your own python interpreter to run them.
{{% /note %}}

Poetry will require you to explicitly specify what versions of Python you intend to support, and its universal locking
will guarantee that your project is installable (and all dependencies claim support for) all supported Python versions.
Again, it's important to remember that -- unlike other dependencies -- setting a Python version is merely specifying which versions of Python you intend to support.

For example, in this pyproject.toml file:

toml

[project]
requires-python = ">=3.9"

we are allowing any version of Python 3 that is greater or equal than 3.9.0.

When you run poetry install, you must have access to some version of a Python interpreter that satisfies this constraint available on your system.
Poetry will not install a Python interpreter for you.

Initialising a pre-existing project

Instead of creating a new project, Poetry can be used to 'initialize' a pre-populated
directory. To interactively create a pyproject.toml file in directory pre-existing-project:

bash

cd pre-existing-project
poetry init

Operating modes

Poetry can be operated in two different modes. The default mode is the package mode, which is the right mode
if you want to package your project into an sdist or a wheel and perhaps publish it to a package index.
In this mode, some metadata such as name and version, which are required for packaging, are mandatory.
Further, the project itself will be installed in editable mode when running poetry install.

If you want to use Poetry only for dependency management but not for packaging, you can use the non-package mode:

toml

[tool.poetry]
package-mode = false

In this mode, metadata such as name and version are optional.
Therefore, it is not possible to build a distribution or publish the project to a package index.
Further, when running poetry install, Poetry does not try to install the project itself,
but only its dependencies (same as poetry install --no-root).

{{% note %}}
In the [pyproject section]({{< relref "pyproject" >}}) you can see which fields are required in package mode.
{{% /note %}}

Specifying dependencies

If you want to add dependencies to your project, you can specify them in the
project section.

toml

[project]
# ...
dependencies = [
    "pendulum (>=2.1,<3.0)"
]

As you can see, it takes a mapping of package names and version constraints.

Poetry uses this information to search for the right set of files in package "repositories" that you register
in the tool.poetry.source section, or on PyPI by default.

Also, instead of modifying the pyproject.toml file by hand, you can use the add command.

bash

$ poetry add pendulum

It will automatically find a suitable version constraint and install the package and sub-dependencies.

Poetry supports a rich [dependency specification]({{< relref "dependency-specification" >}}) syntax, including caret,
tilde, wildcard, inequality and
[multiple constraints]({{< relref "dependency-specification#multiple-constraints-dependencies" >}}) requirements.

Using your virtual environment

By default, Poetry creates a virtual environment in {cache-dir}/virtualenvs.
You can change the [cache-dir]({{< relref "configuration#cache-dir" >}} "cache-dir configuration documentation") value
by editing the Poetry configuration.
Additionally, you can use the
[virtualenvs.in-project]({{< relref "configuration#virtualenvsin-project" >}}) configuration variable to create
virtual environments within your project directory.

There are several ways to run commands within this virtual environment.

{{% note %}}
External virtual environment management

Poetry will detect and respect an existing virtual environment that has been externally activated. This is a powerful
mechanism that is intended to be an alternative to Poetry's built-in, simplified environment management.

To take advantage of this, simply activate a virtual environment using your preferred method or tooling, before running
any Poetry commands that expect to manipulate an environment.
{{% /note %}}

Using `poetry run`

To run your script simply use poetry run python your_script.py.
Likewise if you have command line tools such as pytest or black you can run them using poetry run pytest.

{{% note %}}
If managing your own virtual environment externally, you do not need to use poetry run since
you will, presumably, already have activated that virtual environment and made available the correct python instance.
For example, these commands should output the same python path:

shell

conda activate your_env_name
which python
poetry run which python
eval "$(poetry env activate)"
which python

Activating the virtual environment

See [Activating the virtual environment]({{< relref "managing-environments#activating-the-environment" >}}).

Version constraints

In our example, we are requesting the pendulum package with the version constraint >=2.1.0 <3.0.0.
This means any version greater or equal to 2.1.0 and less than 3.0.0.

Please read [Dependency specification]({{< relref "dependency-specification" >}} "Dependency specification documentation")
for more in-depth information on versions, how versions relate to each other, and on the different ways you can specify
dependencies.

{{% note %}}
How does Poetry download the right files?

When you specify a dependency in pyproject.toml, Poetry first takes the name of the package
that you have requested and searches for it in any repository you have registered using the repositories key.
If you have not registered any extra repositories, or it does not find a package with that name in the
repositories you have specified, it falls back to PyPI.

When Poetry finds the right package, it then attempts to find the best match for the version constraint you have
specified.
{{% /note %}}

Installing dependencies

To install the defined dependencies for your project, just run the [install]({{< relref "cli#install" >}}) command.

bash

poetry install

When you run this command, one of two things may happen:

Installing without `poetry.lock`

If you have never run the command before and there is also no poetry.lock file present,
Poetry simply resolves all dependencies listed in your pyproject.toml file and downloads the latest version of their files.

When Poetry has finished installing, it writes all the packages and their exact versions that it downloaded to the poetry.lock file,
locking the project to those specific versions.
You should commit the poetry.lock file to your project repo so that all people working on the project are locked to the same versions of dependencies (more below).

Installing with `poetry.lock`

This brings us to the second scenario. If there is already a poetry.lock file as well as a pyproject.toml file
when you run poetry install, it means either you ran the install command before,
or someone else on the project ran the install command and committed the poetry.lock file to the project (which is good).

Either way, running install when a poetry.lock file is present resolves and installs all dependencies that you listed in pyproject.toml,
but Poetry uses the exact versions listed in poetry.lock to ensure that the package versions are consistent for everyone working on your project.
As a result you will have all dependencies requested by your pyproject.toml file,
but they may not all be at the very latest available versions
(some dependencies listed in the poetry.lock file may have released newer versions since the file was created).
This is by design, it ensures that your project does not break because of unexpected changes in dependencies.

Committing your `poetry.lock` file to version control

As an application developer

Application developers commit poetry.lock to get more reproducible builds.

Committing this file to VC is important because it will cause anyone who sets up the project
to use the exact same versions of the dependencies that you are using.
Your CI server, production machines, other developers in your team,
everything and everyone runs on the same dependencies,
which mitigates the potential for bugs affecting only some parts of the deployments.
Even if you develop alone, in six months when reinstalling the project you can feel confident
the dependencies installed are still working even if your dependencies released many new versions since then.
(See note below about using the update command.)

{{% warning %}} If you have added the recommended [[build-system]]({{< relref "pyproject#poetry-and-pep-517" >}}) section to your project's pyproject.toml then you can successfully install your project and its dependencies into a virtual environment using a command like pip install -e .. However, pip will not use the lock file to determine dependency versions as the poetry-core build system is intended for library developers (see next section).
{{% /warning %}}

As a library developer

Library developers have more to consider. Your users are application developers, and your library will run in a Python environment you don't control.

The application ignores your library's lock file. It can use whatever dependency version meets the constraints in your pyproject.toml. The application will probably use the latest compatible dependency version. If your library's poetry.lock falls behind some new dependency version that breaks things for your users, you're likely to be the last to find out about it.

A simple way to avoid such a scenario is to omit the poetry.lock file. However, by doing so, you sacrifice reproducibility and performance to a certain extent. Without a lockfile, it can be difficult to find the reason for failing tests, because in addition to obvious code changes an unnoticed library update might be the culprit. Further, Poetry will have to lock before installing a dependency if poetry.lock has been omitted. Depending on the number of dependencies, locking may take a significant amount of time.

If you do not want to give up the reproducibility and performance benefits, consider a regular refresh of poetry.lock to stay up-to-date and reduce the risk of sudden breakage for users.

Installing dependencies only

The current project is installed in editable mode by default.

If you want to install the dependencies only, run the install command with the --no-root flag:

bash

poetry install --no-root

Updating dependencies to their latest versions

As mentioned above, the poetry.lock file prevents you from automatically getting the latest versions
of your dependencies.
To update to the latest versions, use the update command.
This will fetch the latest matching versions (according to your pyproject.toml file)
and update the lock file with the new versions.
(This is equivalent to deleting the poetry.lock file and running install again.)

{{% note %}}
Poetry will display a Warning when executing an install command if poetry.lock and pyproject.toml
are not synchronized.
{{% /note %}}

File: docs/building-extension-modules.md

title: "Building extension modules"
draft: false
type: docs
layout: single

menu:
docs:
weight: 125

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.
{{% /warning %}}

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.

{{< steps >}}
{{< step >}}
Add Build Dependencies

The build dependencies, in this context, refer to those Python packages that are required in order to successfully execute
your build script. Common examples include cython, meson, maturin, setuptools etc., depending on how your
extension is built.

{{% note %}}
You must assume that only Python built-ins are available by default in a build environment. This means, if you need
even packages like setuptools, it must be explicitly declared.
{{% /note %}}

The necessary build dependencies must be added to the build-system.requires section of your pyproject.toml file.

toml

[build-system]
requires = ["poetry-core", "setuptools", "cython"]
build-backend = "poetry.core.masonry.api"

{{% note %}}
It is recommended that you consider specifying version constraints to all entries in build-system.requires in order to
avoid surprises if one of the packages introduce a breaking change. For example, you can set cython to
cython>=3.0.11,<4.0.0 to ensure no major version upgrades are used.
{{% /note %}}

{{% note %}}
If you wish to develop the build script within your project's virtual environment, then you must also add the
dependencies to your project explicitly to a dependency group - the name of which is not important.

poetry add --group=build setuptools cython

{{< step >}}
Add Build Script

The build script can be a free-form Python script that uses any dependency specified in the previous step. This can be
named as needed, but must be located within the project root directory (or a subdirectory) and also must
be included in your source distribution. You can see the [example snippets section]({{< relref "#example-snippets" >}})
for inspiration.

{{% note %}}
The build script is always executed from the project root. And it is expected to move files around to their destinations
as expected by Poetry as per your pyproject.toml file.
{{% /note %}}

toml

[tool.poetry.build]
script = "relative/path/to/build-extension.py"

{{% note %}}
The name of the build script is arbitrary. Common practice has been to name it build.py, however, this is not
mandatory. You should consider [using a subdirectory]({{< relref "#can-i-store-the-build-script-in-a-subdirectory" >}})
if feasible.
{{% /note %}}

{{< step >}}
Specify Distribution Files

{{% warning %}}
The following is an example, and should not be considered as complete.
{{% /warning %}}

toml

[tool.poetry]
...
include = [
    { path = "package/**/*.so", format = "wheel" },
    # sources must be present in sdist, can be ignored if you only have *.pyx sources
    { path = "package/**/*.c", format = "sdist" },
]

The key takeaway here should be the following. You can refer to the [pyproject.toml]({{< relref "pyproject#exclude-and-include" >}})
documentation for information on each of the relevant sections.

Include your build outputs in your wheel.
Exclude your build inputs from your wheel.
Include your build inputs to your source distribution.

Example Snippets

Cython

{{< tabs tabTotal="3" tabID1="cython-pyproject" tabName1="pyproject.toml" tabID2="cython-build-script" tabName2="build-extension.py" tabID3="cython-src-tree" tabName3="Source Tree">}}

toml

[build-system]
requires = ["poetry-core", "cython", "setuptools"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
...
packages = [
    { include = "package", from = "src"},
]
include = [
    { path = "src/package/**/*.so", format = "wheel" },
]
# if not already excluded via .gitignore
exclude = [
    "**/*.c"
]

[tool.poetry.build]
script = "scripts/build-extension.py"

from __future__ import annotations

import os
import shutil

from pathlib import Path

from Cython.Build import cythonize
from setuptools import Distribution
from setuptools import Extension
from setuptools.command.build_ext import build_ext


COMPILE_ARGS = ["-march=native", "-O3", "-msse", "-msse2", "-mfma", "-mfpmath=sse"]
LINK_ARGS = []
INCLUDE_DIRS = []
LIBRARIES = ["m"]


def build() -> None:
    extensions = [
        Extension(
            "*",
            ["src/package/*.pyx"],
            extra_compile_args=COMPILE_ARGS,
            extra_link_args=LINK_ARGS,
            include_dirs=INCLUDE_DIRS,
            libraries=LIBRARIES,
        )
    ]
    ext_modules = cythonize(
        extensions,
        include_path=INCLUDE_DIRS,
        compiler_directives={"binding": True, "language_level": 3},
    )

    distribution = Distribution({
        "name": "package",
        "ext_modules": ext_modules
    })

    cmd = build_ext(distribution)
    cmd.ensure_finalized()
    cmd.run()

    # Copy built extensions back to the project
    for output in cmd.get_outputs():
        output = Path(output)
        relative_extension = Path("src") / output.relative_to(cmd.build_lib)

        shutil.copyfile(output, relative_extension)
        mode = os.stat(relative_extension).st_mode
        mode |= (mode & 0o444) >> 2
        os.chmod(relative_extension, mode)


if __name__ == "__main__":
    build()

text

scripts/
└── build-extension.py
src/
└── package
    ├── example.pyx
    └── __init__.py

Meson

{{< tabs tabTotal="2" tabID1="meson-pyproject" tabName1="pyproject.toml" tabID2="meson-build-script" tabName2="build-extension.py">}}

toml

[tool.poetry.build]
script = "build-extension.py"

[build-system]
requires = ["poetry-core", "meson"]
build-backend = "poetry.core.masonry.api"

from __future__ import annotations

import subprocess

from pathlib import Path


def meson(*args):
    subprocess.call(["meson", *args])


def build():
    build_dir = Path(__file__).parent.joinpath("build")
    build_dir.mkdir(parents=True, exist_ok=True)

    meson("setup", build_dir.as_posix())
    meson("compile", "-C", build_dir.as_posix())
    meson("install", "-C", build_dir.as_posix())


if __name__ == "__main__":
    build()

Maturin

{{< tabs tabTotal="2" tabID1="maturin-pyproject" tabName1="pyproject.toml" tabID2="maturin-build-script" tabName2="build-extension.py">}}

toml

[tool.poetry.build]
script = "build-extension.py"

[build-system]
requires = ["poetry-core", "maturin"]
build-backend = "poetry.core.masonry.api"

import os
import shlex
import shutil
import subprocess
import zipfile

from pathlib import Path


def maturin(*args):
    subprocess.call(["maturin", *list(args)])


def build():
    build_dir = Path(__file__).parent.joinpath("build")
    build_dir.mkdir(parents=True, exist_ok=True)

    wheels_dir = Path(__file__).parent.joinpath("target/wheels")
    if wheels_dir.exists():
        shutil.rmtree(wheels_dir)

    cargo_args = []
    if os.getenv("MATURIN_BUILD_ARGS"):
        cargo_args = shlex.split(os.getenv("MATURIN_BUILD_ARGS", ""))

    maturin("build", "-r", *cargo_args)

    # We won't use the wheel built by maturin directly since
    # we want Poetry to build it, but we need to retrieve the
    # compiled extensions from the maturin wheel.
    wheel = next(iter(wheels_dir.glob("*.whl")))
    with zipfile.ZipFile(wheel.as_posix()) as whl:
        whl.extractall(wheels_dir.as_posix())

        for extension in wheels_dir.rglob("**/*.so"):
            shutil.copyfile(extension, Path(__file__).parent.joinpath(extension.name))

    shutil.rmtree(wheels_dir)


if __name__ == "__main__":
    build()

FAQ

When is my build script executed?

If your project uses a build script, it is run implicitly in the following scenarios.

When poetry install is run, it is executed prior to installing the project's root package.
When poetry build is run, it is executed prior to building distributions.
When a PEP 517 build is triggered from source or sdist by another build frontend.

How does Poetry ensure my build script's dependencies are met?

Prior to executing the build script, Poetry creates a temporary virtual environment with your project's active Python
version and then installs all dependencies specified under build-system.requires into this environment. It should be
noted that no packages will be present in this environment at the time of creation.

Can I store the build script in a subdirectory?

Yes you can. If storing the script in a subdirectory, your pyproject.toml might look something like this.

toml

[tool.poetry]
...
packages = [
    { include = "package", from = "src"}
]
include = [
    { path = "src/package/**/*.so", format = "wheel" },
]
# exclude any intermediate source files
exclude = [
    "**/*.c"
]

[tool.poetry.build]
script = "scripts/build-extension.py"

File: docs/cli.md

title: "Commands"
draft: false
type: docs
layout: single

menu:
docs:
weight: 30

Commands

You've already learned how to use the command-line interface to do some things.
This chapter documents all the available commands.

To get help from the command-line, simply call poetry to see the complete list of commands,
then --help combined with any of those can give you more information.

Global Options

--verbose (-v|vv|vvv): Increase the verbosity of messages: "-v" for normal output, "-vv" for more verbose output and "-vvv" for debug.

{{% note %}}
You can also set the verbosity level using the SHELL_VERBOSITY environment variable.
This is useful in CI/CD pipelines or scripts where you cannot easily modify command-line arguments.

Value	Equivalent	Description
`-1`	`-q`	Quiet mode
`0`	(default)	Normal output
`1`	`-v`	Verbose output
`2`	`-vv`	More verbose output
`3`	`-vvv`	Debug output

--help (-h) : Display help information.
--quiet (-q) : Do not output any message.
--ansi: Force ANSI output.
--no-ansi: Disable ANSI output.
--version (-V): Display this application version.
--no-interaction (-n): Do not ask any interactive question.
--no-plugins: Disables plugins.
--no-cache: Disables the use of [Poetry's caches]({{< relref "#cache" >}}) (cached package metadata and dist files from configured package sources) for the duration of the command, forcing Poetry to behave as if it had a cold cache. This does not delete the caches; use poetry cache clear to remove cached data.
--directory=DIRECTORY (-C): The working directory for the Poetry command (defaults to the current working directory). All command-line arguments will be resolved relative to the given directory.
--project=PROJECT (-P): Specify another path as the project root. All command-line arguments will be resolved relative to the current working directory or directory specified using --directory option if used.

about

The about command displays global information about Poetry, including the current version and version of poetry-core.

bash

poetry about

add

The add command adds required packages to your pyproject.toml and installs them.

If you do not specify a version constraint, poetry will attempt to use the latest version.

bash

poetry add requests pendulum

{{% note %}}
A package is looked up, by default, only from PyPI.
You can modify the default source (PyPI);
or add and use [Supplemental Package Sources]({{< relref "repositories/#supplemental-package-sources" >}})
or [Explicit Package Sources]({{< relref "repositories/#explicit-package-sources" >}}).

For more information, refer to the [Package Sources]({{< relref "repositories/#package-sources" >}}) documentation.
{{% /note %}}

You can also specify a constraint when adding a package:

bash

# Allow >=2.0.5, <3.0.0 versions
poetry add pendulum@^2.0.5

# Allow >=2.0.5, <2.1.0 versions
poetry add pendulum@~2.0.5

# Allow >=2.0.5 versions, without upper bound
poetry add "pendulum>=2.0.5"

# Allow only 2.0.5 version
poetry add pendulum==2.0.5

{{% note %}}
See the [Dependency specification]({{< relref "dependency-specification#using-the--operator" >}}) page for more information about the @ operator.
{{% /note %}}

If you try to add a package that is already present, you will get an error.
However, if you specify a constraint, like above, the dependency will be updated
by using the specified constraint.

If you want to get the latest version of an already
present dependency, you can use the special latest constraint:

bash

poetry add pendulum@latest

{{% note %}}
See the [Dependency specification]({{< relref "dependency-specification" >}}) for more information on setting the version constraints for a package.
{{% /note %}}

You can also add git dependencies:

bash

poetry add git+https://github.com/sdispater/pendulum.git

or use ssh instead of https:

bash

poetry add git+ssh://[email protected]/sdispater/pendulum.git

# or alternatively:
poetry add git+ssh://[email protected]:sdispater/pendulum.git

If you need to checkout a specific branch, tag or revision,
you can specify it when using add:

bash

poetry add git+https://github.com/sdispater/pendulum.git#develop
poetry add git+https://github.com/sdispater/pendulum.git#2.0.5

# or using SSH instead:
poetry add git+ssh://[email protected]:sdispater/pendulum.git#develop
poetry add git+ssh://[email protected]:sdispater/pendulum.git#2.0.5

or reference a subdirectory:

bash

poetry add git+https://github.com/myorg/mypackage_with_subdirs.git@main#subdirectory=subdir

You can also add a local directory or file:

bash

poetry add ./my-package/
poetry add ../my-package/dist/my-package-0.1.0.tar.gz
poetry add ../my-package/dist/my_package-0.1.0.whl

If you want the dependency to be installed in editable mode you can use the --editable option.

bash

poetry add --editable ./my-package/
poetry add --editable git+ssh://github.com/sdispater/pendulum.git#develop

Alternatively, you can specify it in the pyproject.toml file. It means that changes in the local directory will be reflected directly in environment.

toml

[tool.poetry.dependencies]
my-package = {path = "../my/path", develop = true}

{{% note %}}
The develop attribute is a Poetry-specific feature, so it is not included in the package distribution metadata.
In other words, it is only considered when using Poetry to install the project.
{{% /note %}}

If the package(s) you want to install provide extras, you can specify them
when adding the package:

bash

poetry add "requests[security,socks]"
poetry add "requests[security,socks]~=2.22.0"
poetry add "git+https://github.com/pallets/[email protected][dotenv,dev]"

{{% warning %}}
Some shells may treat square braces ([ and ]) as special characters. It is suggested to always quote arguments containing these characters to prevent unexpected shell expansion.
{{% /warning %}}

If you want to add a package to a specific group of dependencies, you can use the --group (-G) option:

bash

poetry add mkdocs --group docs

See [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}) for more information
about dependency groups.

Options

--group (-G): The group to add the dependency to.
--dev (-D): Add package as development dependency. (shortcut for -G dev)
--editable (-e): Add vcs/path dependencies as editable.
--extras (-E): Extras to activate for the dependency. (multiple values allowed)
--optional: Add as an optional dependency to an extra.
--python: Python version for which the dependency must be installed.
--platform: Platforms for which the dependency must be installed.
--markers: Environment markers which describe when the dependency should be installed.
--source: Name of the source to use to install the package.
--allow-prereleases: Accept prereleases.
--dry-run: Output the operations but do not execute anything (implicitly enables --verbose).
--lock: Do not perform install (only update the lockfile).

build

The build command builds the source and wheels archives.

bash

poetry build

The command will trigger the build system defined in the pyproject.toml file according to PEP 517.
If necessary the build process happens in an isolated environment.

Options

--format (-f): Limit the format to either wheel or sdist.
--clean: Clean output directory before building.
--local-version (-l): Add or replace a local version label to the build (deprecated).
--output (-o): Set output directory for build artifacts. Default is dist.
--config-settings=<key>=<value> (-c): Config settings to be passed to the build back-end. (multiple allowed)

{{% note %}}
When using --local-version, the identifier must be PEP 440
compliant. This is useful for adding build numbers, platform specificities, etc. for private packages.

--local-version is deprecated and will be removed in a future version of Poetry.
Use --config-settings local-version=<version> instead.
{{% /note %}}

{{% warning %}}
Local version identifiers SHOULD NOT be used when publishing upstream projects to a public index server, but MAY be
used to identify private builds created directly from the project source.

See PEP 440 for more information.
{{% /warning %}}

cache

The cache command groups subcommands to interact with Poetry's cache.

cache clear

The cache clear command removes packages from cached repositories.

For example, to clear the whole cache of packages from all repositories, run:

bash

poetry cache clear --all

To only clear all packages from the PyPI repository, run:

bash

poetry cache clear PyPI --all

To only remove a specific package from a cache, you have to specify the cache entry in the following form cache:package:version:

bash

poetry cache clear PyPI:requests:2.24.0

cache list

The cache list command lists Poetry's available caches.

bash

poetry cache list

check

The check command validates the content of the pyproject.toml file
and its consistency with the poetry.lock file.
It returns a detailed report if there are any errors.

{{% note %}}
This command is also available as a pre-commit hook. See [pre-commit hooks]({{< relref "pre-commit-hooks#poetry-check">}}) for more information.
{{% /note %}}

bash

poetry check

Options

--lock: Verifies that poetry.lock exists for the current pyproject.toml.
--strict: Fail if check reports warnings.

config

The config command allows you to edit poetry config settings and repositories.

bash

poetry config --list

Usage

bash

poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]

setting-key is a configuration option name and setting-value1 is a configuration value.
See [Configuration]({{< relref "configuration" >}}) for all available settings.

{{% warning %}}
Use -- to terminate option parsing if your values may start with a hyphen (-), e.g.

bash

poetry config http-basic.custom-repo gitlab-ci-token -- ${GITLAB_JOB_TOKEN}

Without -- this command will fail if ${GITLAB_JOB_TOKEN} starts with a hyphen.
{{% /warning%}}

Options

--unset: Remove the configuration element named by setting-key.
--list: Show the list of current config variables.
--local: Set/Get settings that are specific to a project (in the local configuration file poetry.toml).
--migrate: Migrate outdated configuration settings.

debug

The debug command groups subcommands that are useful for, as the name suggests, debugging issues you might have
when using Poetry with your projects.

debug info

The debug info command shows debug information about Poetry and your project's virtual environment.

debug resolve

The debug resolve command helps when debugging dependency resolution issues. The command attempts to resolve your
dependencies and list the chosen packages and versions.

debug tags

The debug tags command is useful when you want to see the supported packaging tags for your project's active
virtual environment. This is useful when Poetry cannot install any known binary distributions for a dependency.

env

The env command groups subcommands to interact with the virtualenvs
associated with a specific project.

See [Managing environments]({{< relref "managing-environments" >}}) for more information about these commands.

env activate

The env activate command prints the command to activate a virtual environment in your current shell.

{{% note %}}
This command does not activate the virtual environment, but only displays the activation command, for more information
on how to use this command see [here]({{< relref "managing-environments#activating-the-environment" >}}).
{{% /note %}}

env info

The env info command displays information about the current environment.

Options

--path (-p): Only display the environment's path.
--executable (-e): Only display the environment's python executable path.

env list

The env list command lists all virtualenvs associated with the current project.

Options

--full-path: Output the full paths of the virtualenvs.

env remove

The env remove command removes virtual environments associated with the project. You can specify multiple Python
executables or virtual environment names to remove all matching ones. Alternatively, you can remove all associated
virtual environments using the --all option.

{{% note %}}
If virtualenvs.in-project config is set to true, no argument or option is required. Your in project virtual environment is removed.
{{% /note %}}

Arguments

python: The python executables associated with, or names of the virtual environments which are to be removed. Can be specified multiple times.

Options

--all: Remove all managed virtual environments associated with the project.

env use

The env use command activates or creates a new virtualenv for the current project.

Arguments

python: The python executable to use. This can be a version number (if not on Windows) or a path to the python binary.

export

{{% warning %}}
This command is provided by the Export Poetry Plugin.
The plugin is no longer installed by default with Poetry 2.0.

See [Using plugins]({{< relref "plugins#using-plugins" >}}) for information on how to install a plugin.
As described in [Project plugins]({{< relref "plugins#project-plugins" >}}),
you can also define in your pyproject.toml that the plugin is required for the development of your project:

toml

[tool.poetry.requires-plugins]
poetry-plugin-export = ">=1.8"

{{% note %}}
The export command is also available as a pre-commit hook.
See [pre-commit hooks]({{< relref "pre-commit-hooks#poetry-export" >}}) for more information.
{{% /note %}}

help

The help command displays global help, or help for a specific command.

To display global help:

bash

poetry help

To display help for a specific command, for instance show:

bash

poetry help show

{{% note %}}
The --help option can also be passed to any command to get help for a specific command.

For instance:

bash

poetry show --help

init

This command will help you create a pyproject.toml file interactively
by prompting you to provide basic information about your package.

It will interactively ask you to fill in the fields, while using some smart defaults.

bash

poetry init

Options

--name: Name of the package.
--description: Description of the package.
--author: Author of the package.
--python Compatible Python versions.
--dependency: Package to require with a version constraint. Should be in format foo:1.0.0.
--dev-dependency: Development requirements, see --dependency.

install

The install command reads the pyproject.toml file from the current project,
resolves the dependencies, and installs them.

bash

poetry install

If there is a poetry.lock file in the current directory,
it will use the exact versions from there instead of resolving them.
This ensures that everyone using the library will get the same versions of the dependencies.

If there is no poetry.lock file, Poetry will create one after dependency resolution.

{{% note %}}
When to use install vs update:

Use poetry install to install dependencies as specified in poetry.lock (or resolve dependencies and create the lock file if it is missing).
This is what you run after cloning a project. For reproducible installs, prefer poetry sync,
which also removes packages that are not in the lock file.
Use poetry update when you want to update dependencies to their latest versions (within the constraints from the pyproject.toml)
and refresh poetry.lock.
{{% /note %}}

{{% note %}}
Normally, you should prefer poetry sync to poetry install to avoid untracked outdated packages.
However, if you have set virtualenvs.create = false to install dependencies into your system environment,
which is discouraged, or virtualenvs.options.system-site-packages = true to make
system site-packages available in your virtual environment, you should use poetry install
because poetry sync will normally not work well in these cases.
{{% /note %}}

If you want to exclude one or more dependency groups for the installation, you can use
the --without option.

bash

poetry install --without test,docs

You can also select optional dependency groups with the --with option.

bash

poetry install --with test,docs

To install all dependency groups including the optional groups, use the --all-groups flag.

bash

poetry install --all-groups

It's also possible to only install specific dependency groups by using the only option.

bash

poetry install --only test,docs

To only install the project itself with no dependencies, use the --only-root flag.

bash

poetry install --only-root

See [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}) for more information
about dependency groups.

You can also specify the extras you want installed
by passing the -E|--extras option (See [Extras]({{< relref "pyproject#extras" >}}) for more info).
Pass --all-extras to install all defined extras for a project.

bash

poetry install --extras "mysql pgsql"
poetry install -E mysql -E pgsql
poetry install --all-extras

Any extras not specified will be kept but not installed:

bash

poetry install --extras "A B"  # C is kept if already installed

If you want to remove unspecified extras, use the sync command.

By default poetry will install your project's package every time you run install:

bash

$ poetry install
Installing dependencies from lock file

No dependencies to install or update

  - Installing <your-package-name> (x.x.x)

If you want to skip this installation, use the --no-root option.

bash

poetry install --no-root

Similar to --no-root you can use --no-directory to skip directory path dependencies:

bash

poetry install --no-directory

This is mainly useful for caching in CI or when building Docker images. See the [FAQ entry]({{< relref "faq#poetry-busts-my-docker-cache-because-it-requires-me-to-copy-my-source-files-in-before-installing-3rd-party-dependencies" >}}) for more information on this option.

By default poetry does not compile Python source files to bytecode during installation.
This speeds up the installation process, but the first execution may take a little more
time because Python then compiles source files to bytecode automatically.
If you want to compile source files to bytecode during installation,
you can use the --compile option:

bash

poetry install --compile

Options

--without: The dependency groups to ignore.
--with: The optional dependency groups to include.
--only: The only dependency groups to include.
--only-root: Install only the root project, exclude all dependencies.
--sync: Synchronize the environment with the locked packages and the specified groups. (Deprecated, use poetry sync instead)
--no-root: Do not install the root package (your project).
--no-directory: Skip all directory path dependencies (including transitive ones).
--dry-run: Output the operations but do not execute anything (implicitly enables --verbose).
--extras (-E): Features to install (multiple values allowed).
--all-extras: Install all extra features (conflicts with --extras).
--all-groups: Install dependencies from all groups (conflicts with --only, --with, and --without).
--compile: Compile Python source files to bytecode.

{{% note %}}
When --only is specified, --with and --without options are ignored.
{{% /note %}}

list

The list command displays all the available Poetry commands.

bash

poetry list

lock

This command locks (without installing) the dependencies specified in pyproject.toml.

{{% note %}}
By default, packages that have already been added to the lock file before will not be updated.
To update all dependencies to the latest available compatible versions, use poetry update --lock
or poetry lock --regenerate, which normally produce the same result.
This command is also available as a pre-commit hook. See [pre-commit hooks]({{< relref "pre-commit-hooks#poetry-lock">}}) for more information.
{{% /note %}}

bash

poetry lock

Options

--regenerate: Ignore existing lock file and overwrite it with a new lock file created from scratch.

new

This command will help you kickstart your new Python project by creating a new Poetry project. By default, a src
layout is chosen.

bash

poetry new my-package

will create a folder as follows:

text

my-package
├── pyproject.toml
├── README.md
├── src
│   └── my_package
│       └── __init__.py
└── tests
    └── __init__.py

If you want to name your project differently than the folder, you can pass
the --name option:

bash

poetry new my-folder --name my-package

If you want to use a flat project layout, you can use the --flat option:

bash

poetry new --flat my-package

That will create a folder structure as follows:

text

my-package
├── pyproject.toml
├── README.md
├── my_package
│   └── __init__.py
└── tests
    └── __init__.py

{{% note %}}
For an overview of the differences between flat and src layouts, please see
here.
{{% /note %}}

The --name option is smart enough to detect namespace packages and create
the required structure for you.

bash

poetry new --name my.package my-package

will create the following structure:

text

my-package
├── pyproject.toml
├── README.md
├── src
│   └── my
│       └── package
│           └── __init__.py
└── tests
    └── __init__.py

Options

--interactive (-i): Allow interactive specification of project configuration.
--name: Set the resulting package name.
--flat: Use the flat layout for the project.
--readme: Specify the readme file extension. Default is md. If you intend to publish to PyPI
keep the recommendations for a PyPI-friendly README
in mind.
--description: Description of the package.
--author: Author of the package.
--python Compatible Python versions.
--dependency: Package to require with a version constraint. Should be in format foo:1.0.0.
--dev-dependency: Development requirements, see --dependency.

publish

This command publishes the package, previously built with the build command, to the remote repository.

It will automatically register the package before uploading if this is the first time it is submitted.

bash

poetry publish

It can also build the package if you pass it the --build option.

{{% note %}}
See [Publishable Repositories]({{< relref "repositories/#publishable-repositories" >}}) for more information
on how to configure and use publishable repositories.
{{% /note %}}

{{% warning %}}
Only artifacts of the latest version of your package in the dist directory will be uploaded.
Older versions from previous builds as well as artifacts of other packages are ignored.
{{% /warning %}}

Options

--repository (-r): The repository to register the package to (default: pypi).
Should match a repository name set by the config command.
--username (-u): The username to access the repository.
--password (-p): The password to access the repository.
--cert: Certificate authority to access the repository.
--client-cert: Client certificate to access the repository.
--dist-dir: Dist directory where built artifacts are stored. Default is dist.
--build: Build the package before publishing.
--dry-run: Perform all actions except upload the package.
--skip-existing: Ignore errors from files already existing in the repository.

{{% note %}}
See [Configuring Credentials]({{< relref "repositories/#configuring-credentials" >}}) for more information on how to configure credentials.
{{% /note %}}

python

The python namespace groups subcommands to manage Python versions.

{{% warning %}}
This is an experimental feature, and can change behaviour in upcoming releases.
{{% /warning %}}

Introduced in 2.1.0

python install

The python install command installs the specified Python version from the Python Standalone Builds project.

bash

poetry python install

Options

--clean (-c): Clean up installation if check fails.
--free-threaded (-t): Use free-threaded version if available. (Same as requesting a version with trailing "t".)
--implementation (-i): Python implementation to use. (cpython, pypy)
--reinstall (-r): Reinstall if installation already exists.

python list

The python list command shows Python versions available in the environment. This includes both installed and
discovered System managed and Poetry managed installations.

bash

poetry python list

Options

--all (-a): List all versions, including those available for download.
--free-threaded (-t): List only free-threaded Python versions.
--implementation (-i): Python implementation to search for.
--managed (-m): List only Poetry managed Python versions.

python remove

The python remove command removes the specified Python version if managed by Poetry.

bash

poetry python remove

Options

--free-threaded (-t): Remove free-threaded version (Same as requesting a version with trailing "t".)
--implementation (-i): Python implementation to remove. (cpython, pypy)

remove

The remove command removes a package from the current
list of installed packages.

bash

poetry remove pendulum

If you want to remove a package from a specific group of dependencies, you can use the --group (-G) option:

bash

poetry remove mkdocs --group docs

See [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}) for more information
about dependency groups.

Options

--group (-G): The group to remove the dependency from.
--dev (-D): Removes a package from the development dependencies. (shortcut for -G dev)
--dry-run : Outputs the operations but will not execute anything (implicitly enables --verbose).
--lock: Do not perform operations (only update the lockfile).

run

The run command executes the given command inside the project's virtualenv.

bash

poetry run python -V

It can also execute one of the scripts defined in pyproject.toml.

So, if you have a script defined like this:

{{< tabs tabTotal="2" tabID1="script-project" tabID2=script-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

toml

[project]
# ...
[project.scripts]
my-script = "my_module:main"

toml

[tool.poetry.scripts]
my-script = "my_module:main"

You can execute it like so:

bash

poetry run my-script

Note that this command has no option.

search

This command searches for packages on a remote index.

bash

poetry search requests pendulum

{{% note %}}
PyPI no longer allows for the search of packages without a browser. Please use https://pypi.org/search
(via a browser) instead.

For more information, please see warehouse documentation
and this discussion.
{{% /note %}}

self

The self namespace groups subcommands to manage the Poetry installation itself.

{{% note %}}
Use of these commands will create the required pyproject.toml and poetry.lock files
for Poetry's runtime environment in your [configuration directory]({{< relref "configuration" >}}).
{{% /note %}}

{{% warning %}}
Especially on Windows, self commands that update or remove packages may be problematic
so that other methods for installing plugins and updating Poetry are recommended.
See [Using plugins]({{< relref "plugins#using-plugins" >}}) and
[Installing Poetry]({{< relref "docs#installation" >}}) for more information.
{{% /warning %}}

self add

The self add command installs Poetry plugins and make them available at runtime. Additionally, it can
also be used to upgrade Poetry's own dependencies or inject additional packages into the runtime
environment

{{% note %}}
The self add command works exactly like the add command.
However, it is different in that the packages managed are for Poetry's runtime environment.

The package specification formats supported by the self add command are the same as the ones supported
by the add command.
{{% /note %}}

For example, to install the poetry-plugin-export plugin, you can run:

bash

poetry self add poetry-plugin-export

To update to the latest poetry-core version, you can run:

bash

poetry self add poetry-core@latest

To add a keyring provider artifacts-keyring, you can run:

bash

poetry self add artifacts-keyring

Options

--editable (-e): Add vcs/path dependencies as editable.
--extras (-E): Extras to activate for the dependency. (multiple values allowed)
--allow-prereleases: Accept prereleases.
--source: Name of the source to use to install the package.
--dry-run: Output the operations but do not execute anything (implicitly enables --verbose).

self install

The self install command ensures all additional packages specified are installed in the current
runtime environment.

{{% note %}}
The self install command works similarly to the install command.
However, it is different in that the packages managed are for Poetry's runtime environment.
{{% /note %}}

bash

poetry self install

Options

--sync: Synchronize the environment with the locked packages and the specified groups. (Deprecated, use poetry self sync instead)
--dry-run: Output the operations but do not execute anything (implicitly enables --verbose).

self lock

The self lock command reads this Poetry installation's pyproject.toml file
located in the [configuration directory]({{< relref "configuration" >}}).
Poetry's own dependencies are locked in the corresponding poetry.lock file.

bash

poetry self lock

Options

--regenerate: Ignore existing lock file and overwrite it with a new lock file created from scratch.

self remove

The self remove command removes an installed addon package.

bash

poetry self remove poetry-plugin-export

Options

--dry-run: Outputs the operations but will not execute anything (implicitly enables --verbose).

self show

The self show command behaves similar to the show command, but
working within Poetry's runtime environment. This lists all packages installed within
the Poetry install environment.

To show only additional packages that have been added via self add and their
dependencies use self show --addons.

bash

poetry self show

Options

--addons: List only add-on packages installed.
--tree: List the dependencies as a tree.
--latest (-l): Show the latest version.
--outdated (-o): Show the latest version but only for packages that are outdated.
--format (-f): Specify the output format (json or text). Default is text. json cannot be combined with the --tree option.

self show plugins

The self show plugins command lists all the currently installed plugins.

bash

poetry self show plugins

self sync

The self sync command ensures all additional (and no other) packages specified
are installed in the current runtime environment.

{{% note %}}
The self sync command works similarly to the sync command.
However, it is different in that the packages managed are for Poetry's runtime environment.
{{% /note %}}

bash

poetry self sync

Options

--dry-run: Output the operations but do not execute anything (implicitly enables --verbose).

self update

The self update command updates the Poetry version and its dependencies
in its current runtime environment.

{{% note %}}
The self update command works exactly like the update command.
However, it is different in that the packages managed are for Poetry's runtime environment.
{{% /note %}}

bash

poetry self update

{{% note %}}
self update uses the package sources configured in Poetry's own pyproject.toml file,
which is located in the [configuration directory]({{< relref "configuration" >}}).
To update Poetry from a custom package source, add a tool.poetry.source entry using
the format described in [Package Sources]({{< relref "repositories/#package-sources" >}}).
Sources configured in the current project's pyproject.toml do not affect self update.
Poetry preserves existing tool.poetry.source entries when it regenerates this file.
{{% /note %}}

Options

--preview: Allow the installation of pre-release versions.
--dry-run: Output the operations but do not execute anything (implicitly enables --verbose).

shell

The shell command was moved to a plugin: poetry-plugin-shell

show

To list all the available packages, you can use the show command.

bash

poetry show

If you want to see the details of a certain package, you can pass the package name.

bash

poetry show pendulum

name        : pendulum
version     : 1.4.2
description : Python datetimes made easy

dependencies
 - python-dateutil >=2.6.1
 - tzlocal >=1.4
 - pytzdata >=2017.2.2

required by
 - calendar requires >=1.4.0

Options

--without: The dependency groups to ignore.
--why: When showing the full list, or a --tree for a single package, display whether they are a direct dependency or required by other packages.
--with: The optional dependency groups to include.
--only: The only dependency groups to include.
--tree: List the dependencies as a tree.
--latest (-l): Show the latest version.
--outdated (-o): Show the latest version but only for packages that are outdated.
--all (-a): Show all packages (even those not compatible with current system).
--top-level (-T): Only show explicitly defined packages.
--no-truncate: Do not truncate the output based on the terminal width.
--format (-f): Specify the output format (json or text). Default is text. json cannot be combined with the --tree option.

{{% note %}}
When --only is specified, --with and --without options are ignored.
{{% /note %}}

source

The source namespace groups subcommands to manage repository sources for a Poetry project.

source add

The source add command adds source configuration to the project.

For example, to add the pypi-test source, you can run:

bash

poetry source add --priority supplemental pypi-test https://test.pypi.org/simple/

You cannot use the name pypi for a custom repository as it is reserved for use by
the default PyPI source. However, you can set the priority of PyPI:

bash

poetry source add --priority=explicit pypi

Options

--priority: Set the priority of this source. Accepted values are: [primary]({{< relref "repositories#primary-package-sources" >}}), [supplemental]({{< relref "repositories#supplemental-package-sources" >}}), and [explicit]({{< relref "repositories#explicit-package-sources" >}}). Refer to the dedicated sections in [Repositories]({{< relref "repositories" >}}) for more information.

source show

The source show command displays information on all configured sources for the project.

bash

poetry source show

Optionally, you can show information of one or more sources by specifying their names.

bash

poetry source show pypi-test

{{% note %}}
This command will only show sources configured via the pyproject.toml
and does not include the implicit default PyPI.
{{% /note %}}

source remove

The source remove command removes a configured source from your pyproject.toml.

bash

poetry source remove pypi-test

sync

The sync command makes sure that the project's environment is in sync with the poetry.lock file.
It is similar to poetry install but it additionally removes packages that are not tracked in the lock file.

bash

poetry sync

If there is no poetry.lock file, Poetry will create one after dependency resolution.

If you want to exclude one or more dependency groups for the installation, you can use
the --without option.

bash

poetry sync --without test,docs

You can also select optional dependency groups with the --with option.

bash

poetry sync --with test,docs

To install all dependency groups including the optional groups, use the --all-groups flag.

bash

poetry sync --all-groups

It's also possible to only install specific dependency groups by using the only option.

bash

poetry sync --only test,docs

To only install the project itself with no dependencies, use the --only-root flag.

bash

poetry sync --only-root

See [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}) for more information
about dependency groups.

bash

poetry sync --extras "mysql pgsql"
poetry sync -E mysql -E pgsql
poetry sync --all-extras

Any extras not specified will always be removed.

bash

poetry sync --extras "A B"  # C is removed

By default poetry will install your project's package every time you run sync:

bash

$ poetry sync
Installing dependencies from lock file

No dependencies to install or update

  - Installing <your-package-name> (x.x.x)

If you want to skip this installation, use the --no-root option.

bash

poetry sync --no-root

Similar to --no-root you can use --no-directory to skip directory path dependencies:

bash

poetry sync --no-directory

bash

poetry sync --compile

Options

--without: The dependency groups to ignore.
--with: The optional dependency groups to include.
--only: The only dependency groups to include.
--only-root: Install only the root project, exclude all dependencies.
--no-root: Do not install the root package (your project).
--no-directory: Skip all directory path dependencies (including transitive ones).
--dry-run: Output the operations but do not execute anything (implicitly enables --verbose).
--extras (-E): Features to install (multiple values allowed).
--all-extras: Install all extra features (conflicts with --extras).
--all-groups: Install dependencies from all groups (conflicts with --only, --with, and --without).
--compile: Compile Python source files to bytecode.

{{% note %}}
When --only is specified, --with and --without options are ignored.
{{% /note %}}

update

In order to get the latest versions of the dependencies and to update the poetry.lock file,
you should use the update command.

bash

poetry update

This will resolve all dependencies of the project, write the exact versions into poetry.lock,
and install them into your environment.

{{% note %}}
The update command does not modify your pyproject.toml file. It only updates the
poetry.lock file with the latest compatible versions based on the constraints already
defined in pyproject.toml. To change version constraints, use the add command instead.
{{% /note %}}

If you just want to update a few packages and not all, you can list them as such:

bash

poetry update requests toml

Note that this will not update versions for dependencies outside their
[version constraints]({{< relref "dependency-specification#version-constraints" >}})
specified in the pyproject.toml file.
In other terms, poetry update foo will be a no-op if the version constraint
specified for foo is ~2.3 or 2.3 and 2.4 is available.
In order for foo to be updated, you must update the constraint, for example ^2.3.
You can do this using the add command.

Options

--without: The dependency groups to ignore.
--with: The optional dependency groups to include.
--only: The only dependency groups to include.
--dry-run : Outputs the operations but will not execute anything (implicitly enables --verbose).
--lock : Do not perform install (only update the lockfile).
--sync: Synchronize the environment with the locked packages and the specified groups.

{{% note %}}
When --only is specified, --with and --without options are ignored.
{{% /note %}}

version

This command shows the current version of the project or bumps the version of
the project and writes the new version back to pyproject.toml if a valid
bump rule is provided.

The new version should be a valid PEP 440
string or a valid bump rule: patch, minor, major, prepatch, preminor,
premajor, prerelease.

If you would like to use semantic versioning for your project, please see
[here]({{< relref "libraries#versioning" >}}).

The table below illustrates the effect of these rules with concrete examples.

rule	before	after
major	1.3.0	2.0.0
minor	2.1.4	2.2.0
patch	4.1.1	4.1.2
premajor	1.0.2	2.0.0a0
preminor	1.0.2	1.1.0a0
prepatch	1.0.2	1.0.3a0
prerelease	1.0.2	1.0.3a0
prerelease	1.0.3a0	1.0.3a1
prerelease	1.0.3b0	1.0.3b1

The option --next-phase allows the increment of prerelease phase versions.

rule	before	after
prerelease --next-phase	1.0.3a0	1.0.3b0
prerelease --next-phase	1.0.3b0	1.0.3rc0
prerelease --next-phase	1.0.3rc0	1.0.3

Options

--next-phase: Increment the phase of the current version.
--short (-s): Output the version number only.
--dry-run: Do not update pyproject.toml file.

File: docs/community.md

title: "Community"
draft: false
type: docs
layout: single

menu:
docs:
weight: 105

Community

Badge

For any projects using Poetry, you may add its official badge somewhere prominent like the README.

Markdown

[](https://python-poetry.org/)

reStructuredText

rst

.. image:: https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json
   :alt: Poetry
   :target: https://python-poetry.org/

File: docs/configuration.md

title: "Configuration"
draft: false
type: docs
layout: single

menu:
docs:
weight: 40

Configuration

Poetry can be configured via the config command ([see more about its usage here]({{< relref "cli#config" >}} "config command documentation"))
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.

bash

poetry config virtualenvs.create false --local

{{% note %}}
Your local configuration of Poetry application is stored in the poetry.toml file,
which is separate from pyproject.toml.
{{% /note %}}

{{% note %}}
If a setting is defined in both poetry.toml (local/project) and config.toml (global),
the local/project configuration takes precedence over the global configuration.
{{% /note %}}

{{% warning %}}
Be mindful when checking in this file into your repository since it may contain user-specific or sensitive information.
{{% /warning %}}

Listing the current configuration

To list the current configuration you can use the --list option
of the config command:

bash

poetry config --list

which will give you something similar to this:

toml

cache-dir = "/path/to/cache/directory"
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = true
virtualenvs.options.no-pip = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "{cache-dir}/virtualenvs"  # /path/to/cache/directory/virtualenvs
virtualenvs.prompt = "{project_name}-py{python_version}"
virtualenvs.use-poetry-python = false

Displaying a single configuration setting

If you want to see the value of a specific setting, you can
give its name to the config command

bash

poetry config virtualenvs.path

For a full list of the supported settings see Available settings.

Adding or updating a configuration setting

To change or otherwise add a new configuration setting, you can pass
a value after the setting's name:

bash

poetry config virtualenvs.path /path/to/cache/directory/virtualenvs

For a full list of the supported settings see Available settings.

Removing a specific setting

If you want to remove a previously set setting, you can use the --unset option:

bash

poetry config virtualenvs.path --unset

The setting will then retrieve its default value.

Using environment variables

Sometimes, in particular when using Poetry with CI tools, it's easier
to use environment variables and not have to execute configuration commands.

Poetry supports this and any setting can be set by using environment variables.

The environment variables must be prefixed by POETRY_ and are comprised of the uppercase
name of the setting and with dots and dashes replaced by underscore, here is an example:

bash

export POETRY_VIRTUALENVS_PATH=/path/to/virtualenvs/directory

This also works for secret settings, like credentials:

bash

export POETRY_HTTP_BASIC_MY_REPOSITORY_PASSWORD=secret

Configuration sources

When a setting is set in multiple places, Poetry applies the following precedence
(from highest to lowest):

Environment variables (for example, POETRY_VIRTUALENVS_CREATE)
The local poetry.toml file (created with poetry config --local)
The global config.toml file
The setting's default value

For repository credentials (http-basic.*, pypi-token.*), Poetry may also read
from auth.toml and the system keyring (for details see [Repositories]({{< relref "repositories" >}})).
Environment variables still take precedence over file-based values.

Migrate outdated configs

If Poetry renames or remove config options it might be necessary to migrate explicit set options. This is possible
by running:

bash

poetry config --migrate

If you need to migrate a local config run:

bash

poetry config --migrate --local

Default Directories

Poetry uses the following default directories:

Config Directory

Linux: $XDG_CONFIG_HOME/pypoetry or ~/.config/pypoetry
Windows: %APPDATA%\pypoetry
macOS: ~/Library/Application Support/pypoetry

You can override the config directory by setting the POETRY_CONFIG_DIR environment variable.

Data Directory

Linux: $XDG_DATA_HOME/pypoetry or ~/.local/share/pypoetry
Windows: %APPDATA%\pypoetry
macOS: ~/Library/Application Support/pypoetry

You can override the data directory by setting the POETRY_DATA_DIR or POETRY_HOME environment variables. If POETRY_HOME is set, it will be given higher priority.

Cache Directory

Linux: $XDG_CACHE_HOME/pypoetry or ~/.cache/pypoetry
Windows: %LOCALAPPDATA%\pypoetry
macOS: ~/Library/Caches/pypoetry

You can override the cache directory by setting the POETRY_CACHE_DIR environment variable.

Available settings

`cache-dir`

Type: string

Environment Variable: POETRY_CACHE_DIR

The path to the cache directory used by Poetry.

Defaults to one of the following directories:

macOS: ~/Library/Caches/pypoetry
Windows: C:\Users\\AppData\Local\pypoetry\Cache
Unix: ~/.cache/pypoetry

`data-dir`

Type: string

Environment Variable: POETRY_DATA_DIR

The path to the data directory used by Poetry.

Linux: $XDG_DATA_HOME/pypoetry or ~/.local/share/pypoetry
Windows: %APPDATA%\pypoetry
macOS: ~/Library/Application Support/pypoetry

You can override the data directory by setting the POETRY_DATA_DIR or POETRY_HOME environment variables. If
POETRY_HOME is set, it will be given higher priority.

`installer.max-workers`

Type: int

Default: number_of_cores + 4

Environment Variable: POETRY_INSTALLER_MAX_WORKERS

Introduced in 1.2.0

Set the maximum number of workers while using the parallel installer.
The number_of_cores is determined by os.cpu_count().
If this raises a NotImplementedError exception, number_of_cores is assumed to be 1.

If this configuration parameter is set to a value greater than number_of_cores + 4,
the number of maximum workers is still limited at number_of_cores + 4.

{{% note %}}
This configuration is ignored when installer.parallel is set to false.
{{% /note %}}

`installer.no-binary`

Type: string | boolean

Default: false

Environment Variable: POETRY_INSTALLER_NO_BINARY

Introduced in 1.2.0

When set, this configuration allows users to disallow the use of binary distribution format for all, none or specific packages.

Configuration	Description
`:all:` or `true`	Disallow binary distributions for all packages.
`:none:` or `false`	Allow binary distributions for all packages.
`package[,package,..]`	Disallow binary distributions for specified packages only.

If both installer.no-binary and installer.only-binary are set, explicit package names will take precedence over :all:.

{{% note %}}
As with all configurations described here, this is a user specific configuration. This means that this
is not taken into consideration when a lockfile is generated or dependencies are resolved. This is
applied only when selecting which distribution for dependency should be installed into a Poetry managed
environment.
{{% /note %}}

{{% note %}}
For project specific usage, it is recommended that this be configured with the --local.

bash

poetry config --local installer.no-binary :all:

{{% note %}}
For CI or container environments using environment variable
to configure this might be useful.

bash

export POETRY_INSTALLER_NO_BINARY=:all:

{{% warning %}}
Unless this is required system-wide, if configured globally, you could encounter slower install times
across all your projects if incorrectly set.
{{% /warning %}}

`installer.only-binary`

Type: string | boolean

Default: false

Environment Variable: POETRY_INSTALLER_ONLY_BINARY

Introduced in 2.0.0

When set, this configuration allows users to enforce the use of binary distribution format for all, none or
specific packages.

{{% note %}}
Please refer to [installer.no-binary]({{< relref "configuration#installerno-binary" >}}) for information on allowed
values, usage instructions and warnings.
{{% /note %}}

`installer.parallel`

Type: boolean

Default: true

Environment Variable: POETRY_INSTALLER_PARALLEL

Introduced in 1.1.4

Use parallel execution when using the new (>=1.1.0) installer.

`installer.build-config-settings.`

Type: Serialised JSON with string or list of string properties

Default: None

Environment Variable: POETRY_INSTALLER_BUILD_CONFIG_SETTINGS_

Introduced in 2.1.0

{{% warning %}}
This is an experimental configuration and can be subject to changes in upcoming releases until it is considered
stable.
{{% /warning %}}

Configure PEP 517 config settings to be passed to a package's
build backend if it has to be built from a directory or vcs source; or a source distribution during installation.

This is only used when a compatible binary distribution (wheel) is not available for a package. This can be used along
with [installer.no-binary]({{< relref "configuration#installerno-binary" >}}) option to force a build with these
configurations when a dependency of your project with the specified name is being installed.

{{% note %}}
Poetry does not offer a similar option in the pyproject.toml file as these are, in majority of cases, not universal
and vary depending on the target installation environment.

If you want to use a project specific configuration it is recommended that this configuration be set locally, in your
project's poetry.toml file.

bash

poetry config --local installer.build-config-settings.grpcio \
  '{"CC": "gcc", "--global-option": ["--some-global-option"], "--build-option": ["--build-option1", "--build-option2"]}'

If you want to modify a single key, you can do, by setting the same key again.

bash

poetry config --local installer.build-config-settings.grpcio \
  '{"CC": "g++"}'

`requests.max-retries`

Type: int

Default: 0

Environment Variable: POETRY_REQUESTS_MAX_RETRIES

Introduced in 2.0.0

Set the maximum number of retries in an unstable network.
This setting has no effect if the server does not support HTTP range requests.

`installer.re-resolve`

Type: boolean

Default: false

Environment Variable: POETRY_INSTALLER_RE_RESOLVE

Changed default from true to false in 2.3.0

Introduced in 2.0.0

If the config option is not set and the lock file is at least version 2.1
(created by Poetry 2.0 or above), the installer will not re-resolve dependencies
but evaluate the locked markers to decide which of the locked dependencies have to
be installed into the target environment.

`python.installation-dir`

Type: string

Default: {data-dir}/python

Environment Variable: POETRY_PYTHON_INSTALLATION_DIR

Introduced in 2.1.0

The directory in which Poetry managed Python versions are installed to.

`solver.lazy-wheel`

Type: boolean

Default: true

Environment Variable: POETRY_SOLVER_LAZY_WHEEL

Introduced in 1.8.0

Do not download entire wheels to extract metadata but use
HTTP range requests
to only download the METADATA files of wheels.
Especially with slow network connections, this setting can speed up dependency resolution significantly.
If the cache has already been filled or the server does not support HTTP range requests,
this setting makes no difference.

`solver.min-release-age`

Type: int

Default: 0

Environment Variable: POETRY_SOLVER_MIN_RELEASE_AGE

Introduced in 2.4.0

Minimum age of a package release in days before it is considered during dependency resolution.
When set, any package version where at least one distribution file was uploaded more recently
than the specified number of days ago will be ignored by the solver.

For example, with a value of 7, a version is only considered
if all known distribution files are at least seven days old.
If the option is not set or set to 0, all versions are considered.

This option is useful to protect against supply chain attacks where a new release
of a dependency is published with malicious code.
This is often detected within hours or days and the compromised release is removed.

{{% note %}}
This filter can only be enforced for package sources that expose file upload timestamps.
If a source does not provide upload times for a release,
that release is not filtered out by this setting.
{{% /note %}}

`solver.min-release-age-exclude`

Type: string

Default: not set

Environment Variable: POETRY_SOLVER_MIN_RELEASE_AGE_EXCLUDE

Introduced in 2.4.0

A comma-separated list of package names that should be excluded from the
solver.min-release-age filter.
Versions of these packages will always be considered by the solver,
regardless of their upload age.

bash

poetry config solver.min-release-age-exclude "my-package,other-package"

`solver.min-release-age-exclude-source`

Type: string

Default: not set

Environment Variable: POETRY_SOLVER_MIN_RELEASE_AGE_EXCLUDE_SOURCE

Introduced in 2.4.0

A comma-separated list of source names or URLs that should be excluded from the
solver.min-release-age filter.
All packages from these sources will always be considered by the solver,
regardless of their upload age.
Sources can be referenced by the name defined in pyproject.toml or by URL.

bash

poetry config solver.min-release-age-exclude-source "private-repo,https://example.com/simple/"

`system-git-client`

Type: boolean

Default: false

Environment Variable: POETRY_SYSTEM_GIT_CLIENT

Renamed to system-git-client in 2.0.0

Introduced in 1.2.0 as experimental.system-git-client

Use system git client backend for git related tasks.

Poetry uses dulwich by default for git related tasks to not rely on the availability of a git client.

If you encounter any problems with it, set to true to use the system git backend.

`virtualenvs.create`

Type: boolean

Default: true

Environment Variable: POETRY_VIRTUALENVS_CREATE

Create a new virtual environment if one doesn't already exist.

If set to false, Poetry will not create a new virtual environment. If it detects an already enabled virtual
environment or an existing one in {cache-dir}/virtualenvs or {project-dir}/.venv it will
install dependencies into them, otherwise it will install dependencies into the systems python environment.

{{% note %}}
If Poetry detects it's running within an activated virtual environment, it will never create a new virtual environment,
regardless of the value set for virtualenvs.create.
{{% /note %}}

{{% note %}}
Be aware that installing dependencies into the system environment likely upgrade or uninstall existing packages and thus
break other applications. Installing additional Python packages after installing the project might break the Poetry
project in return.

This is why it is recommended to always create a virtual environment. This is also true in Docker containers, as they
might contain additional Python packages as well.
{{% /note %}}

`virtualenvs.in-project`

Type: boolean

Default: None

Environment Variable: POETRY_VIRTUALENVS_IN_PROJECT

Create the virtualenv inside the project's root directory.

If not set explicitly, poetry by default will create a virtual environment under
{cache-dir}/virtualenvs or use the {project-dir}/.venv directory if one already exists.

If set to true, the virtualenv will be created and expected in a folder named
.venv within the root directory of the project.

{{% note %}}
If a virtual environment has already been created for the project under {cache-dir}/virtualenvs, setting this variable to true will not cause poetry to create or use a local virtual environment.

In order for this setting to take effect for a project already in that state, you must delete the virtual environment folder located in {cache-dir}/virtualenvs.

You can find out where the current project's virtual environment (if there is one) is stored
with the command poetry env info --path.
{{% /note %}}

If set to false, poetry will ignore any existing .venv directory.

`virtualenvs.options.always-copy`

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_OPTIONS_ALWAYS_COPY

Introduced in 1.2.0

If set to true the --always-copy parameter is passed to virtualenv on creation of the virtual environment, so that
all needed files are copied into it instead of symlinked.

`virtualenvs.options.no-pip`

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_OPTIONS_NO_PIP

Introduced in 1.2.0

If set to true the --no-pip parameter is passed to virtualenv on creation of the virtual environment. This means
when a new virtual environment is created, pip will not be installed in the environment.

{{% note %}}
Poetry, for its internal operations, uses the pip wheel embedded in the virtualenv package installed as a dependency
in Poetry's runtime environment. If a user runs poetry run pip when this option is set to true, the pip the
embedded instance of pip is used.

You can safely set this to true, if you desire a virtual environment with no additional packages.
This is desirable for production environments.
{{% /note %}}

`virtualenvs.options.system-site-packages`

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_OPTIONS_SYSTEM_SITE_PACKAGES

Give the virtual environment access to the system site-packages directory.
Applies on virtualenv creation.

`virtualenvs.path`

Type: string

Default: {cache-dir}/virtualenvs

Environment Variable: POETRY_VIRTUALENVS_PATH

Directory where virtual environments will be created.

{{% note %}}
This setting controls the global virtual environment storage path. It most likely will not be useful at the local level. To store virtual environments in the project root, see virtualenvs.in-project.
{{% /note %}}

`virtualenvs.prompt`

Type: string

Default: {project_name}-py{python_version}

Environment Variable: POETRY_VIRTUALENVS_PROMPT

Introduced in 1.2.0

Format string defining the prompt to be displayed when the virtual environment is activated.
The variables project_name and python_version are available for formatting.

`virtualenvs.use-poetry-python`

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_USE_POETRY_PYTHON

Introduced in 2.0.0

By default, Poetry will use the activated Python version to create a new virtual environment.
If set to true, the Python version used during Poetry installation is used.

`repositories..url`

Type: string

Environment Variable: POETRY_REPOSITORIES_<NAME>_URL

Set the repository URL for <name>.

See [Publishable Repositories]({{< relref "repositories#publishable-repositories" >}}) for more information.

`http-basic..[username|password]`

Type: string

Environment Variables: POETRY_HTTP_BASIC_<NAME>_USERNAME, POETRY_HTTP_BASIC_<NAME>_PASSWORD

Set repository credentials (username and password) for <name>.
See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}})
for more information.

`pypi-token.`

Type: string

Environment Variable: POETRY_PYPI_TOKEN_<NAME>

Set repository credentials (using an API token) for <name>.
See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}})
for more information.

`certificates..cert`

Type: string | boolean

Environment Variable: POETRY_CERTIFICATES_<NAME>_CERT

Set custom certificate authority for repository <name>.
See [Repositories - Configuring credentials - Custom certificate authority]({{< relref "repositories#custom-certificate-authority-and-mutual-tls-authentication" >}})
for more information.

This configuration can be set to false, if TLS certificate verification should be skipped for this
repository.

`certificates..client-cert`

Type: string

Environment Variable: POETRY_CERTIFICATES_<NAME>_CLIENT_CERT

Set client certificate for repository <name>.
See [Repositories - Configuring credentials - Custom certificate authority]({{< relref "repositories#custom-certificate-authority-and-mutual-tls-authentication" >}})
for more information.

`keyring.enabled`

Type: boolean

Default: true

Environment Variable: POETRY_KEYRING_ENABLED

Enable the system keyring for storing credentials.
See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}})
for more information.

File: docs/contributing.md

title: "Contributing to Poetry"
draft: false
type: docs
layout: single

menu:
docs:
weight: 100

note: "Are you viewing this document on GitHub? For the best experience, view it on the website https://python-poetry.org/docs/contributing."

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.

Before submitting a bug report

Check the [FAQ] for a list of common questions and problems.
Check the [blog] for release notes from recent releases, including steps for upgrading and known issues.
Check that your issue does not already exist in the issue tracker.
Make sure your issue is really a bug, and is not a support request or question better suited for [Discussions]
or Discord.
Try running your commands with the --no-cache flag.
Try clearing your cache with poetry cache clear --all PyPI and rerunning your commands.

{{% note %}}
If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and
include a link to the original issue in the body of your new one.
{{% /note %}}

How do I submit a bug report?

Bugs concerning Poetry and poetry-core should be submitted to the main issue tracker, using the correct
[issue template].

Explain the problem and make it easy for others to search for and understand:

Use a clear and descriptive title for the issue to identify the problem.
Describe the exact steps which reproduce the problem in as many details as possible.
Describe the behavior you observed after following the steps and point out how this is a bug.
Explain which behavior you expected to see instead and why.
If the problem involves an unexpected error being raised, execute the problematic command in debug mode
(with -vvv flag).

Provide detailed steps for reproduction of your issue:

Provide your pyproject.toml file in a Gist, pastebin, or example repository after
removing potential private information like private package repositories or names.
Provide specific examples to demonstrate the steps to reproduce the issue. This could be an example repository, a
sequence of steps run in a container, or just a pyproject.toml for very simple cases.
Are you unable to reliably reproduce the issue? If so, provide details about how often the problem happens
and under which conditions it normally happens.

Provide more context by answering these questions:

Did the problem start happening recently (e.g., after updating to a new version of Poetry) or was this always a
problem?
If the problem started happening recently, can you reproduce the problem in an older version of Poetry? What's the
most recent version in which the problem does not happen?
Is there anything exotic or unusual about your environment? This could include use of special container images,
newer CPU architectures like Apple Silicon, or corporate proxies that intercept or modify your network traffic.

Include details about your configuration and environment:

Which version of Poetry are you using? You can get the exact version by running poetry --version.
What version of Python is being used to run Poetry? Execute the poetry debug info to get this information.
What's the name and version of the OS you're using? Examples include Ubuntu 22.04 or macOS 12.6.

To give others the best chance to understand and reproduce your issue, please be sure to put extra effort into your
reproduction steps. You can both rule out local configuration issues on your end, and ensure others can cleanly
reproduce your issue if attempt all reproductions in a pristine container (or VM), and provide the steps you performed
inside that container/VM in your issue report.

Suggesting enhancements

This section guides you through submitting an enhancement suggestion for Poetry, including completely new features as
well as improvements to existing functionality. Following these guidelines helps maintainers and the community
understand your suggestion and find related suggestions.

Before submitting a suggested enhancement

Check the [FAQ] for a list of common questions and problems.
Check that your issue does not already exist in the issue tracker.

How do I submit a suggested enhancement?

Suggested enhancements concerning Poetry and poetry-core should be submitted to the main issue tracker, using the
correct [issue template].

Use a clear and descriptive title for the issue to identify the suggestion.
Provide a detailed description of the proposed enhancement, with specific steps or examples when possible.
Describe the current behavior and explain which behavior you would like to see instead, and why.

Documentation contributions

One of the simplest ways to get started contributing to a project is through improving documentation. Poetry is
constantly evolving, and this means that sometimes our documentation has gaps. You can help by adding missing sections,
editing the existing content to be more accessible, or creating new content such as tutorials, FAQs, etc.

{{% note %}}
GitHub Discussions and the
kind/question label are excellent sources for FAQ
candidates.
{{% /note %}}

Issues pertaining to the documentation are usually marked with the [area/docs label], which will also trigger a preview
of the changes as rendered by this website.

Code contributions

Picking an issue

{{% note %}}
If you are a first time contributor, and are looking for an issue to take on, you might want to look for
at the contributing page for candidates. We do our best to curate
good issues for first-time contributors there, but do fall behind -- so if you don't see anything good, feel free to
ask.
{{% /note %}}

If you would like to take on an issue, feel free to comment on the issue tagging @python-poetry/triage.
We are more than happy to discuss solutions on the issue. If you would like help with navigating the code base, are
looking for something to work on, or want feedback on a design or change, join us on our Discord server or
start a [Discussion][Discussions].

Local development

Poetry is developed using Poetry. Refer to the documentation to install Poetry in your local environment.

{{% note %}}
Poetry's development toolchain requires Python 3.9 or newer.
{{% /note %}}

You should first fork the Poetry repository and then clone it locally, so that you can make pull requests against the
project. If you are new to Git and pull request-based development, GitHub provides a
guide you will find helpful.

Next, you should install Poetry's dependencies, and run the test suite to make sure everything is working as expected:

bash

poetry install
poetry run pytest

{{% note %}}
If you want to see the coverage stats after the tests are complete, use:

bash

poetry run pytest --cov=src/poetry --cov-report term

When you contribute to Poetry, automated tools will be run to make sure your code is suitable to be merged. Besides
pytest, you will need to make sure your code typechecks properly using mypy:

bash

poetry run mypy

Finally, a great deal of linting tools are run on your code, to try and ensure consistent code style and root out common
mistakes. The pre-commit tool is used to install and run these tools, and requires one-time
setup:

bash

poetry run pre-commit install

pre-commit will now run and check your code every time you make a commit. By default, it will only run on changed files,
but you can run it on all files manually (this may be useful if you altered the pre-commit config):

bash

poetry run pre-commit run --all-files

Pull requests

Fill out the pull request body completely and describe your changes as accurately as possible. The pull request body
should be kept up to date as it will usually form the base for the final merge commit and the changelog entry.
Be sure that your pull request contains tests that cover the changed or added code. Tests are generally required for
code be to be considered mergeable, and code without passing tests will not be merged.
Ensure your pull request passes the mypy and pre-commit checks. Remember that you can run these tools locally
instead of relying on remote CI.
If your changes warrant a documentation change, the pull request must also update the documentation. Make sure to
review the documentation preview generated by CI for any rendering issues.

{{% note %}}
Make sure your branch is rebased against the latest
base branch. A maintainer might ask you to ensure the branch is up-to-date prior to merging your pull request
(especially if there have been CI changes on the base branch), and will also ask you to fix any conflicts.
{{% /note %}}

All pull requests, unless otherwise instructed, need to be first accepted into the main branch. Maintainers will
generally decide if any backports to other branches are required, and carry them out as needed.

Issue triage

{{% note %}}
If you have an issue that hasn't had any attention, you can ping us @python-poetry/triage on the issue. Please give us
reasonable time to get to your issue first, and avoid pinging any individuals directly, especially if they are not part
of the Poetry team.
{{% /note %}}

If you are helping with the triage of reported issues, this section provides some useful information to assist you in
your contribution.

Triage steps

Determine what area and versions of Poetry the issue is related to, and set the appropriate labels (e.g.
version/x.x.x, area/docs, area/venv), and remove the status/triage label.
If requested information (such as debug logs, pyproject.toml, etc.) is not provided and is relevant, request it from
the author.
1. Set the status/waiting-on-response label while waiting to hear back from the author.
Attempt to reproduce the issue with the reported Poetry version or request further clarification from the author.
Ensure the issue is not already resolved. Try reproducing it on the latest stable release, the latest prerelease (if
present), and the development branch.
If the issue cannot be reproduced,
1. request more reproduction steps and clarification from the issue's author,
2. set the status/needs-reproduction label,
3. close the issue if there is no reproduction forthcoming.
If the issue can be reproduced,
1. comment on the issue confirming so,
2. set the status/confirmed label,
3. if possible, identify the root cause of the issue,
4. if interested, attempt to fix it via a pull request.

Multiple versions

When trying to reproduce issues, you often want to use multiple versions of Poetry at the same time.
pipx makes this easy to do:

pipx install --suffix @1.2.1 'poetry==1.2.1'
pipx install --suffix @1.3.0rc1 'poetry==1.3.0rc1'
pipx install --suffix @main 'poetry @ git+https://github.com/python-poetry/poetry'
pipx install --suffix @local '/path/to/local/clone/of/poetry'

# now you can use any of the chosen versions of Poetry with their configured suffix, e.g.
poetry@main --version

{{% note %}}
Do not forget to pipx upgrade poetry@main before using it, to make sure you have the latest changes.
{{% /note %}}

{{% note %}}
This mechanism can also be used to test pull requests by using GitHub's pull request remote refs:

pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head

[Blog]: {{< ref "/blog" >}}
Documentation: {{< ref "/docs" >}}
[FAQ]: {{< relref "faq" >}}
Issue Tracker: https://github.com/python-poetry/poetry/issues
[area/docs label]: https://github.com/python-poetry/poetry/labels/area%2Fdocs
[Issue Template]: https://github.com/python-poetry/poetry/issues/new/choose
[Discussions]: https://github.com/python-poetry/poetry/discussions
Discord: https://discord.com/invite/awxPgve

File: docs/dependency-specification.md

title: "Dependency specification"
draft: false
type: docs
layout: single

menu:
docs:
weight: 70

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.

toml

[tool.poetry.dependencies]
requests = "^2.13.0"

With Poetry 2.0, you should consider using the project.dependencies section instead.

toml

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

In many cases, tool.poetry.dependencies can be replaced with project.dependencies.
However, there are some cases where you might still need to use tool.poetry.dependencies.
For example, if you want to define additional information that is not required for building
but only for locking (for example, an explicit source), you can enrich dependency
information in the tool.poetry section.

toml

[project]
# ...
dependencies = [
    "requests>=2.13.0",
]

[tool.poetry.dependencies]
requests = { source = "private-source" }

When both are specified, project.dependencies are used for metadata when building the project,
tool.poetry.dependencies is only used to enrich project.dependencies for locking.

Alternatively, you can add dependencies to dynamic and define your dependencies
completely in the tool.poetry section. Using only the tool.poetry section might
make sense in non-package mode when you will not build an sdist or a wheel.

toml

[project]
# ...
dynamic = [ "dependencies" ]

[tool.poetry.dependencies]
requests = { version = ">=2.13.0", source = "private-source" }

{{% note %}}
Another use case for tool.poetry.dependencies are relative path dependencies
since project.dependencies only support absolute paths.
{{% /note %}}

{{% note %}}
Only main dependencies can be specified in the project section.
Other [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}})
must still be specified in the tool.poetry section.
{{% /note %}}

Version constraints

Compatible release requirements

Compatible release requirements specify a minimal version with the ability to update to later versions of the same level.
For example, if you specify a major, minor, and patch version, only patch-level changes are allowed.
If you only specify a major, and minor version, then minor- and patch-level changes are allowed.

~=1.2.3 is an example of a compatible release requirement.

Requirement	Versions allowed
~=1.2.3	>=1.2.3 <1.3.0
~=1.2	>=1.2.0 <2.0.0

Wildcard requirements

Wildcard requirements allow for the latest (dependency-dependent) version where the wildcard is positioned.

*, 1.* and 1.2.* are examples of wildcard requirements.

Requirement	Versions allowed
*	>=0.0.0
1.*	>=1.0.0 <2.0.0
1.2.*	>=1.2.0 <1.3.0

Inequality requirements

Inequality requirements allow manually specifying a version range or an exact version to depend on.

Here are some examples of inequality requirements:

text

>= 1.2.0
> 1
< 2
!= 1.2.3

Multiple requirements

Multiple version requirements can also be separated with a comma, e.g. >= 1.2, < 1.5.

Exact requirements

You can specify the exact version of a package.

1.2.3 is an example of an exact version specification.

This will tell Poetry to install this version and this version only.
If other dependencies require a different version, the solver will ultimately fail and abort any installation or update procedures.

Exact versions can also be specified with == according to PEP 440.

==1.2.3 is an example of this.

Caret requirements

{{% warning %}}
Not supported in project.dependencies.

When using poetry add such constraints are automatically converted into an equivalent constraint.
{{% /warning %}}

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.13.0 and wanted to update the library and ran poetry update requests, poetry would update us to version 2.14.0 if it was available, but would not update us to 3.0.0. If instead, we had specified the version string as ^0.1.13, poetry would update to 0.1.14 but not 0.2.0. 0.0.x is not considered compatible with any other version.

Here are some more examples of caret requirements and the versions that would be allowed with them:

Requirement	Versions allowed
^1.2.3	>=1.2.3 <2.0.0
^1.2	>=1.2.0 <2.0.0
^1	>=1.0.0 <2.0.0
^0.2.3	>=0.2.3 <0.3.0
^0.0.3	>=0.0.3 <0.0.4
^0.0	>=0.0.0 <0.1.0
^0	>=0.0.0 <1.0.0

Tilde requirements

{{% warning %}}
Not supported in project.dependencies.

When using poetry add such constraints are automatically converted into an equivalent constraint.
{{% /warning %}}

Tilde requirements specify a minimal version with some ability to update.
If you specify a major, minor, and patch version or only a major and minor version, only patch-level changes are allowed.
If you only specify a major version, then minor- and patch-level changes are allowed.

~1.2.3 is an example of a tilde requirement.

Requirement	Versions allowed
~1.2.3	>=1.2.3 <1.3.0
~1.2	>=1.2.0 <1.3.0
~1	>=1.0.0 <2.0.0

Using the `@` operator

When adding dependencies via poetry add, you can use the @ operator.
This is understood similarly to the == syntax, but also allows prefixing any
specifiers that are valid in pyproject.toml. For example:

shell

poetry add "django@^4.0.0"

The above would translate to the following entry in pyproject.toml:

{{< tabs tabTotal="2" tabID1="at-project" tabID2="at-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

toml

[project]
# ...
dependencies = [
    "django (>=4.0.0,<5.0.0)",
]

toml

[tool.poetry.dependencies]
django = "^4.0.0"

The special keyword latest is also understood by the @ operator:

shell

poetry add django@latest

The above would translate to the following entry in pyproject.toml, assuming the latest release of django is 5.1.3:

{{< tabs tabTotal="2" tabID1="at-latest-project" tabID2="at-latest-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

toml

[project]
# ...
dependencies = [
    "django (>=5.1.3,<6.0.0)",
]

toml

[tool.poetry.dependencies]
django = "^5.1.3"

Extras

Extras and @ can be combined as one might expect (package[extra]@version):

shell

poetry add django[bcrypt]@^4.0.0

`git` dependencies

To depend on a library located in a git repository,
the minimum information you need to specify is the location of the repository:

{{< tabs tabTotal="2" tabID1="git-project" tabID2="git-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

toml

[project]
# ...
dependencies = [
    "requests @ git+https://github.com/requests/requests.git",
]

{{< tab tabID="git-poetry" >}}
In the tool.poetry section you use the git key:

toml

[tool.poetry.dependencies]
requests = { git = "https://github.com/requests/requests.git" }

Since we haven’t specified any other information,
Poetry assumes that we intend to use the latest commit on the main branch
to build our project.

You can explicitly specify which branch, commit hash or tagged ref should be used:

{{< tabs tabTotal="2" tabID1="git-rev-project" tabID2="git-rev-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

{{< tab tabID="git-rev-project" >}}
Append the information to the git url.

toml

[project]
# ...
dependencies = [
    "requests @ git+https://github.com/requests/requests.git@next",
    "flask @ git+https://github.com/pallets/flask.git@38eb5d3b",
    "numpy @ git+https://github.com/numpy/[email protected]",
]

{{< tab tabID="git-rev-poetry" >}}
Combine the git key with the branch, rev or tag key respectively.

toml

[tool.poetry.dependencies]
# Get the latest revision on the branch named "next"
requests = { git = "https://github.com/kennethreitz/requests.git", branch = "next" }
# Get a revision by its commit hash
flask = { git = "https://github.com/pallets/flask.git", rev = "38eb5d3b" }
# Get a revision by its tag
numpy = { git = "https://github.com/numpy/numpy.git", tag = "v0.13.2" }

It's possible to add a package that is located in a subdirectory of the VCS repository.

{{< tabs tabTotal="2" tabID1="git-subdir-project" tabID2="git-subdir-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

{{< tab tabID="git-subdir-project" >}}
Provide the subdirectory as a URL fragment similarly to what pip provides.

toml

[project]
# ...
dependencies = [
    "subdir_package @ git+https://github.com/myorg/mypackage_with_subdirs.git#subdirectory=subdir"
]

{{< tab tabID="git-subdir-poetry" >}}
Use the subdirectory key in the tool.poetry section:

toml

[tool.poetry.dependencies]
# Install a package named `subdir_package` from a folder called `subdir` within the repository
subdir_package = { git = "https://github.com/myorg/mypackage_with_subdirs.git", subdirectory = "subdir" }

The corresponding add call looks like this:

bash

poetry add "git+https://github.com/myorg/mypackage_with_subdirs.git#subdirectory=subdir"

To use an SSH connection, for example, in the case of private repositories, use the following example syntax:

{{< tabs tabTotal="2" tabID1="git-ssh-project" tabID2="git-ssh-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

toml

[project]
# ...
dependencies = [
    "pendulum @ git+ssh://[email protected]/sdispater/pendulum.git"
]

toml

[tool.poetry.dependencies]
pendulum = { git = "[email protected]/sdispater/pendulum.git" }

Credentials for git dependencies

To use HTTP basic authentication with your git repositories, you can configure credentials similar to
how [repository credentials]({{< relref "repositories#configuring-credentials" >}}) are configured.

bash

poetry config repositories.git-org-project https://github.com/org/project.git
poetry config http-basic.git-org-project username token
poetry add git+https://github.com/org/project.git

{{% note %}}
The default git client used is Dulwich.

We fall back to legacy system git client implementation in cases where
gitcredentials is used. This fallback will be removed in
a future release where gitcredentials helpers can be better supported natively.

In cases where you encounter issues with the default implementation, you may wish to
explicitly configure the use of the system git client via a shell subprocess call.

bash

poetry config system-git-client true

`path` dependencies

{{< tabs tabTotal="2" tabID1="path-project" tabID2="path-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

{{< tab tabID="path-project" >}}
In the project section, you can only use absolute paths:

toml

[project]
# directory
dependencies = [
    "my-package @ file:///absolute/path/to/my-package"
]
# file
dependencies = [
    "my-package @ file:///absolute/path/to/my-package/dist/my-package-0.1.0.tar.gz"
]

{{< tab tabID="path-poetry" >}}
To depend on a library located in a local directory or file,
you can use the path property:

toml

[tool.poetry.dependencies]
# directory
my-package = { path = "../my-package/", develop = true }

# file
my-package = { path = "../my-package/dist/my-package-0.1.0.tar.gz" }

To install directory path dependencies in editable mode, use the develop keyword and set it to true.
{{< /tab >}}
{{< /tabs >}}

`url` dependencies

url dependencies are libraries located on a remote archive.

{{< tabs tabTotal="2" tabID1="url-project" tabID2="url-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

toml

[project]
# ...
dependencies = [
    "my-package @ https://example.com/my-package-0.1.0.tar.gz"
]

{{< tab tabID="url-poetry" >}}
Use the url property.

toml

[tool.poetry.dependencies]
# directory
my-package = { url = "https://example.com/my-package-0.1.0.tar.gz" }

The corresponding add call is:

bash

poetry add https://example.com/my-package-0.1.0.tar.gz

Dependency `extras`

You can specify PEP-508 Extras
for a dependency as shown here.

{{< tabs tabTotal="2" tabID1="extras-project" tabID2="extras-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

toml

[project]
# ...
dependencies = [
    "gunicorn[gevent] (>=20.1,<21.0)"
]

toml

[tool.poetry.dependencies]
gunicorn = { version = "^20.1", extras = ["gevent"] }

{{% note %}}
These activate extra defined for the dependency, to configure an optional dependency
for extras in your project refer to [extras]({{< relref "pyproject#extras" >}}).
{{% /note %}}

`source` dependencies

{{% note %}}
It is not possible to define source dependencies in the project section.
{{% /note %}}

To depend on a package from an [alternate repository]({{< relref "repositories#installing-from-private-package-sources" >}}),
you can use the source property:

toml

[[tool.poetry.source]]
name = "foo"
url = "https://foo.bar/simple/"
priority = "supplemental"

[tool.poetry.dependencies]
my-cool-package = { version = "*", source = "foo" }

with the corresponding add call:

poetry add my-cool-package --source foo

{{% note %}}
In this example, we expect foo to be configured correctly. See [using a private repository]({{< relref "repositories#installing-from-private-package-sources" >}})
for further information.
{{% /note %}}

Python restricted dependencies

You can also specify that a dependency should be installed only for specific Python versions:

{{< tabs tabTotal="2" tabID1="python-restriction-project" tabID2="python-restriction-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

toml

[project]
# ...
dependencies = [
    "tomli (>=2.0.1,<3.0) ; python_version < '3.11'",
    "pathlib2 (>=2.2,<3.0) ; python_version >= '3.9' and python_version < '4.0'"
]

toml

[tool.poetry.dependencies]
tomli = { version = "^2.0.1", python = "<3.11" }
pathlib2 = { version = "^2.2", python = "^3.9" }

Using environment markers

If you need more complex install conditions for your dependencies,
Poetry supports environment markers:

{{< tabs tabTotal="2" tabID1="markers-project" tabID2="markers-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

toml

[project]
# ...
dependencies = [
    "pathlib2 (>=2.2,<3.0) ; python_version <= '3.4' or sys_platform == 'win32'"
]

{{< tab tabID="markers-poetry" >}}
Use the markers property:

toml

[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", markers = "python_version <= '3.4' or sys_platform == 'win32'" }

`extra` environment marker

Poetry populates the extra marker with each of the selected extras of the root package.
For example, consider the following dependency:

toml

[project.optional-dependencies]
paths = [
    "pathlib2 (>=2.2,<3.0) ; sys_platform == 'win32'"
]

pathlib2 will be installed when you install your package with --extras paths on a win32 machine.

Exclusive extras

{{% warning %}}
The first example will only work completely if you configure Poetry to not re-resolve for installation:

bash

poetry config installer.re-resolve false

This was a new feature of Poetry 2.0 and became the default behavior in Poetry 2.3.

Keep in mind that all combinations of possible extras available in your project need to be compatible with each other.
This means that in order to use differing or incompatible versions across different combinations, you need to make your
extra markers exclusive. For example, the following installs PyTorch from one source repository with CPU versions
when the cuda extra is not specified, while the other installs from another repository with a separate version set
for GPUs when the cuda extra is specified:

toml

[project]
name = "torch-example"
requires-python = ">=3.10"
dependencies = [
    "torch (==2.3.1+cpu) ; extra != 'cuda'",
]

[project.optional-dependencies]
cuda = [
    "torch (==2.3.1+cu118)",
]

[tool.poetry]
package-mode = false

[tool.poetry.dependencies]
torch = [
    { markers = "extra != 'cuda'", source = "pytorch-cpu"},
    { markers = "extra == 'cuda'", source = "pytorch-cuda"},
 ]

[[tool.poetry.source]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
priority = "explicit"

[[tool.poetry.source]]
name = "pytorch-cuda"
url = "https://download.pytorch.org/whl/cu118"
priority = "explicit"

For the CPU case, we have to specify "extra != 'cuda'" because the version specified is not compatible with the
GPU (cuda) version.

This same logic applies when you want either-or extras:

toml

[project]
name = "torch-example"
requires-python = ">=3.10"

[project.optional-dependencies]
cpu = [
    "torch (==2.3.1+cpu)",
]
cuda = [
    "torch (==2.3.1+cu118)",
]

[tool.poetry]
package-mode = false

[tool.poetry.dependencies]
torch = [
    { markers = "extra == 'cpu' and extra != 'cuda'", source = "pytorch-cpu"},
    { markers = "extra == 'cuda' and extra != 'cpu'", source = "pytorch-cuda"},
 ]

[[tool.poetry.source]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
priority = "explicit"

[[tool.poetry.source]]
name = "pytorch-cuda"
url = "https://download.pytorch.org/whl/cu118"
priority = "explicit"

Multiple constraints dependencies

Sometimes, one of your dependencies may have different version ranges depending
on the target Python versions.

Let's say you have a dependency on the package foo which is only compatible
with Python 3.6–3.7 up to version 1.9, and compatible with Python 3.8+ from version 2.0:
you would declare it like so:

{{< tabs tabTotal="2" tabID1="multiple-constraints-project" tabID2="multiple-constraints-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}

toml

[project]
# ...
dependencies = [
    "foo (<=1.9) ; python_version >= '3.6' and python_version < '3.8'",
    "foo (>=2.0,<3.0) ; python_version >= '3.8'"
]

toml

[tool.poetry.dependencies]
foo = [
    {version = "<=1.9", python = ">=3.6,<3.8"},
    {version = "^2.0", python = ">=3.8"}
]

{{% note %}}
The constraints must have different requirements (like python)
otherwise it will cause an error when resolving dependencies.
{{% /note %}}

Combining git / url / path dependencies with source repositories

Direct origin (git/ url/ path) dependencies can satisfy the requirement of a dependency that
doesn't explicitly specify a source, even when mutually exclusive markers are used. For instance,
in the following example, the url package will also be a valid solution for the second requirement:

toml

foo = [
    { platform = "darwin", url = "https://example.com/example-1.0-py3-none-any.whl" },
    { platform = "linux", version = "^1.0" },
]

Sometimes you may instead want to use a direct origin dependency for specific conditions
(i.e., a compiled package that is not available on PyPI for a certain platform/architecture) while
falling back on source repositories in other cases. In this case you should explicitly ask for your
dependency to be satisfied by another source. For example:

toml

foo = [
    { platform = "darwin", url = "https://example.com/foo-1.0.0-py3-none-macosx_11_0_arm64.whl" },
    { platform = "linux", version = "^1.0", source = "pypi" },
]

Expanded dependency specification syntax

In the case of more complex dependency specifications, you may find that you
end up with lines which are very long and difficult to read. In these cases,
you can shift from using "inline table" syntax to the "standard table" syntax.

An example where this might be useful is the following:

toml

[tool.poetry.group.dev.dependencies]
black = {version = "19.10b0", allow-prereleases = true, python = "^3.7", markers = "platform_python_implementation == 'CPython'"}

As a single line, this is a lot to digest. To make this a bit easier to
work with, you can do the following:

toml

[tool.poetry.group.dev.dependencies.black]
version = "19.10b0"
allow-prereleases = true
python = "^3.7"
markers = "platform_python_implementation == 'CPython'"

The same information is still present, and ends up providing the exact
same specification. It's simply split into multiple, slightly more readable,
lines.

Handling of pre-releases

Per default, Poetry will prefer stable releases and only choose a pre-release
if no stable release satisfies a version constraint. In some cases, this may result in
a solution containing pre-releases even if another solution without pre-releases exists.

If you want to disallow pre-releases for a specific dependency,
you can set allow-prereleases to false. In this case, dependency resolution will
fail if there is no solution without choosing a pre-release.

If you want to prefer the latest version of a dependency even if it is a pre-release,
you can set allow-prereleases to true so that Poetry makes no distinction
between stable and pre-release versions during dependency resolution.

File: docs/faq.md

title: "FAQ"
draft: false
type: docs
layout: single

menu:
docs:
weight: 110

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. At this point, Poetry has no choice
but to download the packages and inspect them to get the necessary information. This is an expensive
operation, both in bandwidth and time, which is why it seems this is a long process.

At the moment, there is no way around it. However, if you notice that Poetry
is downloading many versions of a single package, you can lessen the workload
by constraining that one package in your pyproject.toml more narrowly. That way,
Poetry does not have to sift through so many versions of it, which may speed up
the locking process considerably in some cases.

{{% note %}}
Once Poetry has cached the releases' information on your machine, the dependency resolution process
will be much faster.
{{% /note %}}

What kind of versioning scheme does Poetry use for itself?

Poetry uses "major.minor.micro" version identifiers as mentioned in
PEP 440.

Version bumps are done similar to Python's versioning:

A major version bump (incrementing the first number) is only done for breaking changes
if a deprecation cycle is not possible, and many users have to perform some manual steps
to migrate from one version to the next one.
A minor version bump (incrementing the second number) may include new features as well
as new deprecations and drop features deprecated in an earlier minor release.
A micro version bump (incrementing the third number) usually only includes bug fixes.
Deprecated features will not be dropped in a micro release.

Why does Poetry not adhere to semantic versioning?

Because of its large user base, even small changes not considered relevant by most users
can turn out to be a breaking change for some users in hindsight.
Sticking to strict semantic versioning and (almost) always bumping
the major version instead of the minor version does not seem desirable
since the minor version will not carry any meaning anymore.

Are unbound version constraints a bad idea?

A version constraint without an upper bound such as * or >=3.4 will allow updates to any future version of the dependency.
This includes major versions breaking backward compatibility.

Once a release of your package is published, you cannot tweak its dependencies anymore in case a dependency breaks BC
– you have to do a new release but the previous one stays broken.
(Users can still work around the broken dependency by restricting it by themselves.)

To avoid such issues, you can define an upper bound on your constraints,
which you can increase in a new release after testing that your package is compatible
with the new major version of your dependency.

For example, instead of using >=3.4 you can use ^3.4 which allows all versions <4.0.
The ^ operator works very well with libraries following semantic versioning.

However, when defining an upper bound, users of your package are not able to update
a dependency beyond the upper bound even if it does not break anything
and is fully compatible with your package.
You have to release a new version of your package with an increased upper-bound first.

If your package is used as a library in other packages, it might be better to avoid
upper bounds and thus unnecessary dependency conflicts (unless you already know for sure
that the next release of the dependency will break your package).
If your package is used as an application, it might be worth defining an upper bound.

Is tox supported?

Yes. Provided that you are using tox >= 4, you can use it in combination with
the PEP 517 compliant build system provided by Poetry. (With tox 3, you have to set the
isolated build option.)

So, in your pyproject.toml file, add this section if it does not already exist:

toml

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

tox can be configured in multiple ways. It depends on what should be the code under test and which dependencies
should be installed.

Use case #1

ini

[tox]

[testenv]
deps =
    pytest
commands =
    pytest tests/ --import-mode importlib

tox will create an sdist package of the project and uses pip to install it in a fresh environment.
Thus, dependencies are resolved by pip.

Use case #2

ini

[tox]

[testenv]
allowlist_externals = poetry
commands_pre =
    poetry install --no-root --sync
commands =
    poetry run pytest tests/ --import-mode importlib

tox will create an sdist package of the project and uses pip to install it in a fresh environment.
Thus, dependencies are resolved by pip in the first place. But afterward, we run Poetry,
which will install the locked dependencies into the environment.

Use case #3

ini

[tox]

[testenv]
skip_install = true
allowlist_externals = poetry
commands_pre =
    poetry install
commands =
    poetry run pytest tests/ --import-mode importlib

tox will not do any install. Poetry installs all the dependencies and the current package in editable mode.
Thus, tests are running against the local files and not the built and installed package.

Note about credentials

Note that tox does not forward the environment variables of your current shell session by default.
This may cause Poetry to not be able to install dependencies in the tox environments if you have configured
credentials using the system keyring on Linux systems or using environment variables in general.
You can use the passenv configuration option to forward the
required variables explicitly or passenv = "*" to forward all of them.
Linux systems may require forwarding the DBUS_SESSION_BUS_ADDRESS variable to allow access to the system keyring,
though this may vary between desktop environments.

Alternatively, you can disable the keyring completely:

bash

poetry config keyring.enabled false

Be aware that this will cause Poetry to write passwords to plaintext config files.
You will need to set the credentials again after changing this setting.

Is Nox supported?

Use the nox-poetry package to install locked versions of
dependencies specified in poetry.lock into Nox sessions.

I don't want Poetry to manage my virtual environments. Can I disable it?

While Poetry automatically creates virtual environments to always work isolated
from the global Python installation, there are rare scenarios where the use of a Poetry managed
virtual environment is not possible or preferred.

In this case, you can disable this feature by setting the virtualenvs.create setting to false:

bash

poetry config virtualenvs.create false

{{% warning %}}
The recommended best practice, including when installing an application within a container, is to make
use of a virtual environment. This can also be managed by another tool.

The Poetry team strongly encourages the use of a virtual environment.
{{% /warning %}}

Why is Poetry telling me that the current project's supported Python range is not compatible with one or more packages' Python requirements?

Unlike pip, Poetry doesn't resolve for just the Python in the current environment. Instead, it makes sure that a dependency
is resolvable within the given Python version range in pyproject.toml.

Assume you have the following pyproject.toml:

toml

[tool.poetry.dependencies]
python = "^3.7"

This means your project aims to be compatible with any Python version >=3.7,<4.0. Whenever you try to add a dependency
whose Python requirement doesn't match the whole range, Poetry will tell you this, e.g.:

text

The current project's supported Python range (>=3.7.0,<4.0.0) is not compatible with some of the required packages Python requirement:
    - scipy requires Python >=3.7,<3.11, so it will not be installable for Python >=3.11,<4.0.0

Usually you will want to match the supported Python range of your project with the upper bound of the failing dependency.
Alternatively, you can tell Poetry to install this dependency [only for a specific range of Python versions]({{< relref "dependency-specification#multiple-constraints-dependencies" >}}),
if you know that it's not needed in all versions.

If you do not want to set an upper bound in the metadata when building your project,
you can omit it in the project section and only set it in tool.poetry.dependencies:

toml

[project]
# ...
requires-python = ">=3.7"  # used for metadata when building the project

[tool.poetry.dependencies]
python = ">=3.7,<3.11"  # used for locking dependencies

Why does Poetry enforce PEP 440 versions?

This is done to be compliant with the broader Python ecosystem.

For example, if Poetry builds a distribution for a project that uses a version that is not valid, according to
PEP 440, third party tools will be unable to parse the version correctly.

Poetry busts my Docker cache because it requires me to COPY my source files in before installing 3rd party dependencies

By default, running poetry install ... requires you to have your source files present (both the "root" package and any directory path dependencies you might have).
This interacts poorly with Docker's caching mechanisms because any change to a source file will make any layers (subsequent commands in your Dockerfile) re-run.
For example, you might have a Dockerfile that looks something like this:

text

FROM python
COPY pyproject.toml poetry.lock .
COPY src/ ./src
RUN pip install poetry && poetry install --only main

As soon as any source file changes, the cache for the RUN layer will be invalidated, which forces all 3rd party dependencies (likely the slowest step out of these) to be installed again if you changed any files in src/.

To avoid this cache busting you can split this into two steps:

Install 3rd party dependencies.
Copy over your source code and install just the source code.

This might look something like this:

text

FROM python
COPY pyproject.toml poetry.lock .
RUN pip install poetry && poetry install --only main --no-root --no-directory
COPY src/ ./src
RUN poetry install --only main

The two key options we are using here are --no-root (skips installing the project source) and --no-directory (skips installing any local directory path dependencies, you can omit this if you don't have any).
[More information on the options available for poetry install]({{< relref "cli#install" >}}).

My requests are timing out!

Poetry's default HTTP request timeout is 15 seconds, the same as pip.
Similar to PIP_REQUESTS_TIMEOUT, the experimental environment variable POETRY_REQUESTS_TIMEOUT
can be set to alter this value.

How do I migrate an existing Poetry project using `tools.poetry` section to use the new `project` section (PEP 621)?

{{% note %}}
Poetry >=2.0.0 should seamlessly support both tools.poetry section only configuration as well using the project section. This
lets you decide when and if you would like to migrate to using the project section as described by PyPA.

See documentation on [the pyproject.toml file]({{< relref "pyproject" >}}), for information specific to Poetry.
{{% /note %}}

Due to the nature of this change some manual changes to your pyproject.toml file is unavoidable in order start using the project section. The following tabs
show a transition example. If you wish to retain Poetry's richer [dependency specification]({{< relref "dependency-specification" >}}) syntax it is recommended that
you use dynamic dependencies as described in the second tab below.

{{< tabs tabTotal="3" tabID1="migrate-pep621-old" tabName1="Original" tabID2="migrate-pep621-new-dynamic" tabName2="Using Dynamic Dependencies" tabID3="migrate-pep621-new-static" tabName3="Using Static Dependencies">}}

toml

[tool.poetry]
name = "foobar"
version = "0.1.0"
description = ""
authors = ["Baz Qux "]
readme = "README.md"
packages = [{ include = "awesome", from = "src" }]
include = [{ path = "tests", format = "sdist" }]
homepage = "https://python-foobar.org/"
repository = "https://github.com/python-foobar/foobar"
documentation = "https://python-foobar.org/docs"
keywords = ["packaging", "dependency", "foobar"]
classifiers = [
    "Topic :: Software Development :: Build Tools",
    "Topic :: Software Development :: Libraries :: Python Modules",
]

[tool.poetry.scripts]
foobar = "foobar.console.application:main"

[tool.poetry.dependencies]
python = "^3.13"
httpx = "^0.28.1"

[tool.poetry.group.dev.dependencies]
pre-commit = ">=2.10"

[tool.poetry.group.test.dependencies]
pytest = ">=8.0"

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

toml

[project]
name = "foobar"
version = "0.1.0"
description = ""
authors = [
    { name = "Baz Qux", email = "[email protected]" }
]
readme = "README.md"
requires-python = ">=3.13"
keywords = ["packaging", "dependency", "foobar"]
# classifiers property is dynamic because we want to create Python classifiers automatically
# dependencies are dynamic because we want to keep Poetry's rich dependency definition format
dynamic = ["classifiers", "dependencies"]

[project.urls]
homepage = "https://python-foobar.org/"
repository = "https://github.com/python-foobar/foobar"
documentation = "https://python-foobar.org/docs"

[project.scripts]
foobar = "foobar.console.application:main"

[tool.poetry]
requires-poetry = ">=2.0"
packages = [{ include = "foobar", from = "src" }]
include = [{ path = "tests", format = "sdist" }]
classifiers = [
    "Topic :: Software Development :: Build Tools",
    "Topic :: Software Development :: Libraries :: Python Modules",
]

[tool.poetry.dependencies]
httpx = "^0.28.1"

[tool.poetry.group.dev.dependencies]
pre-commit = ">=2.10"

[tool.poetry.group.test.dependencies]
pytest = ">=8.0"

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

toml

[project]
name = "foobar"
version = "0.1.0"
description = ""
authors = [
    { name = "Baz Qux", email = "[email protected]" }
]
readme = "README.md"
requires-python = ">=3.13"
keywords = ["packaging", "dependency", "foobar"]
# classifiers property is dynamic because we want to create Python classifiers automatically
dynamic = ["classifiers"]
dependencies = [
    "httpx (>=0.28.1,<0.29.0)"
]

[project.urls]
homepage = "https://python-foobar.org/"
repository = "https://github.com/python-foobar/foobar"
documentation = "https://python-foobar.org/docs"

[project.scripts]
foobar = "foobar.console.application:main"

[tool.poetry]
requires-poetry = ">=2.0"
packages = [{ include = "foobar", from = "src" }]
include = [{ path = "tests", format = "sdist" }]
classifiers = [
    "Topic :: Software Development :: Build Tools",
    "Topic :: Software Development :: Libraries :: Python Modules",
]

[tool.poetry.group.dev.dependencies]
pre-commit = ">=2.10"

[tool.poetry.group.test.dependencies]
pytest = ">=8.0"

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

The classifiers property is dynamic to allow Poetry to create and manage Python classifiers in accordance with supported Python version.
The python dependency, in this example was replaced with project.requires-python. However, note that if you need an upper bound on supported Python versions refer to the documentation [here]({{< relref "pyproject#requires-python" >}}).
The [requires-poetry]({{< relref "pyproject#requires-poetry" >}}) is added to the tools.poetry section.
{{% /note %}}

2. Official Technical Reference & Guides (python-poetry/install.python-poetry.org)

Python Poetry Installer

This repository contains Poetry's official installation script, installer source and
related hosting configuration.

The script is hosted on Vercel and made available at
https://install.python-poetry.org/.

Usage

Poetry provides a custom installer that will install poetry isolated
from the rest of your system.

osx / linux / bashonwindows / Windows+MinGW install instructions

bash

curl -sSL https://install.python-poetry.org | python3 -

windows powershell install instructions

powershell

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

If you have installed Python through the Microsoft Store, replace py with python in the command above.

Warning: The previous get-poetry.py installer is now deprecated, if you are currently using it
you should migrate to the new, supported, install.python-poetry.org installer.

The installer installs the poetry tool to Poetry's bin directory. This location depends on your system:

$HOME/.local/bin for Unix
%APPDATA%\Python\Scripts on Windows

If this directory is not on your PATH, you will need to add it manually
if you want to invoke Poetry with simply poetry.

Alternatively, you can use the full path to poetry to use it.

Once Poetry is installed you can execute the following:

bash

poetry --version

If you see something like Poetry (version 1.2.0) then you are ready to use Poetry.
If you decide Poetry isn't your thing, you can completely remove it from your system
by running the installer again with the --uninstall option or by setting
the POETRY_UNINSTALL environment variable before executing the installer:

bash

curl -sSL https://install.python-poetry.org | python3 - --uninstall
curl -sSL https://install.python-poetry.org | POETRY_UNINSTALL=1 python3 -

By default, Poetry is installed into the user's platform-specific home directory.
If you wish to change this, you may define the POETRY_HOME environment variable:

bash

curl -sSL https://install.python-poetry.org | POETRY_HOME=/etc/poetry python3 -

If you want to install prerelease versions, you can do so by passing --preview option or by using the POETRY_PREVIEW
environment variable:

bash

curl -sSL https://install.python-poetry.org | python3 - --preview
curl -sSL https://install.python-poetry.org | POETRY_PREVIEW=1 python3 -

Similarly, if you want to install a specific version, you can use --version option or the POETRY_VERSION
environment variable:

bash

curl -sSL https://install.python-poetry.org | python3 - --version 1.2.0
curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 python3 -

You can also install Poetry for a git repository by using the --git option:

bash

curl -sSL https://install.python-poetry.org | python3 - --git https://github.com/python-poetry/poetry.git@master

Note: The installer does not support Python < 3.6.

Known Issues

Debian/Ubuntu

On Debian and Ubuntu systems, there are various issues that maybe caused due to how
various Python standard library components are packaged and configured. The following
details issues we are presently aware of, and potential workarounds.

Note: This can also affect WSL users on Windows.

Installation Layout

If you encounter an error similar to the following, this might be due to
pypa/virtualenv#2350.

console

FileNotFoundError: [Errno 2] No such file or directory: '/root/.local/share/pypoetry/venv/bin/python'

You can work around this issue by setting the DEB_PYTHON_INSTALL_LAYOUT environment
variable to deb in order to emulate previously working behaviour.

bash

export DEB_PYTHON_INSTALL_LAYOUT=deb

Missing `distutils` Module

In certain Debian/Ubuntu environments, you might encounter the following error message
in error logs (poetry-installer-error-*.log) provided when the installer fails.

console

ModuleNotFoundError: No module named 'distutils.cmd'

This is probably due to this bug.
See also pypa/get-pip#124.

The known workaround for this issue is to reinstall the distutils package provided by
the distribution.

bash

apt-get install --reinstall python3-distutils

If you have installed a specific python version, eg: 3.10, you might have to use the
package name python3.10-distutils.

1. Project Overview & Quickstart (python-poetry/poetry) Copy Chapter

File: README.md Copy Chapter

Poetry: Python packaging and dependency management made easy

Installation Copy Chapter

Documentation Copy Chapter

Contribute Copy Chapter

Resources Copy Chapter

Related Projects Copy Chapter

Supporters Copy Chapter

File: docs/_index.md Copy Chapter

Introduction

System requirements Copy Chapter

Installation Copy Chapter

Enable tab completion for Bash, Fish, or Zsh Copy Chapter

Bash Copy Section

Auto-loaded (recommended)

Lazy-loaded

Fish Copy Section

Zsh Copy Section

Oh My Zsh

Prezto

File: docs/basic-usage.md Copy Chapter

Basic usage

Project setup Copy Chapter

Setting a Python Version Copy Section

Initialising a pre-existing project Copy Section

Operating modes Copy Section

Specifying dependencies Copy Section

Using your virtual environment Copy Chapter

Using `poetry run` Copy Section

Activating the virtual environment Copy Section

Version constraints Copy Chapter

Installing dependencies Copy Chapter

Installing without `poetry.lock` Copy Section

Installing with `poetry.lock` Copy Section

Committing your `poetry.lock` file to version control Copy Section

As an application developer

As a library developer

Installing dependencies only Copy Section

Updating dependencies to their latest versions Copy Chapter

File: docs/building-extension-modules.md Copy Chapter

Building Extension Modules

Example Snippets Copy Chapter

Cython Copy Section

Meson Copy Section

Maturin Copy Section

FAQ Copy Chapter

When is my build script executed? Copy Section

How does Poetry ensure my build script's dependencies are met? Copy Section

Can I store the build script in a subdirectory? Copy Section

File: docs/cli.md Copy Chapter

Commands

Global Options Copy Chapter

about Copy Chapter

add Copy Chapter

Options

build Copy Chapter

Options

cache Copy Chapter

cache clear Copy Section

cache list Copy Section

check Copy Chapter

Options

config Copy Chapter

Usage Copy Section

Options

debug Copy Chapter

debug info Copy Section

debug resolve Copy Section

debug tags Copy Section

env Copy Chapter

env activate Copy Section

env info Copy Section

Options

env list Copy Section

Options

env remove Copy Section

Arguments

Options

env use Copy Section

1. Project Overview & Quickstart (python-poetry/poetry)

File: README.md

Installation

Documentation

Contribute

Resources

Related Projects

Supporters

File: docs/_index.md

System requirements

Installation

Enable tab completion for Bash, Fish, or Zsh

Bash

Fish

Zsh

File: docs/basic-usage.md

Project setup

Setting a Python Version

Initialising a pre-existing project

Operating modes

Specifying dependencies

Using your virtual environment

Using `poetry run`

Activating the virtual environment

Version constraints

Installing dependencies

Installing without `poetry.lock`

Installing with `poetry.lock`

Committing your `poetry.lock` file to version control

Installing dependencies only

Updating dependencies to their latest versions

File: docs/building-extension-modules.md

Example Snippets

Cython

Meson

Maturin

FAQ

When is my build script executed?

How does Poetry ensure my build script's dependencies are met?

Can I store the build script in a subdirectory?

File: docs/cli.md

Global Options

about

add

build

cache

cache clear

cache list

check

config

Usage

debug

debug info

debug resolve

debug tags

env

env activate

env info

env list

env remove

env use

export

help

init

install

list

lock

new

publish

python

python install

python list

python remove

remove

run

search

self

self add

self install

self lock