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

## File: README.md

# Poetry: Python packaging and dependency management made easy

[](https://python-poetry.org/)
[][PyPI Releases]
[][PyPI Releases]
[][PyPI]
[](https://pypistats.org/packages/poetry)
[][Discord]

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.

```
/* 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

* [Releases][PyPI Releases]
* [Official Website]
* [Documentation]
* [Issue Tracker]
* [Discord]

  [PyPI]: https://pypi.org/project/poetry/
  [PyPI Releases]: https://pypi.org/project/poetry/#history
  [Official Website]: https://python-poetry.org
  [Documentation]: https://python-poetry.org/docs/
  [Issue Tracker]: https://github.com/python-poetry/poetry/issues
  [Suggested Issues]: https://github.com/python-poetry/poetry/contribute
  [Contributing Documentation]: https://python-poetry.org/docs/contributing
  [Discord]: https://discord.com/invite/awxPgve
  [install.python-poetry.org]: https://install.python-poetry.org
  [Installation Documentation]: https://python-poetry.org/docs/#installation

## Related Projects

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

## Supporters

Thanks to [JetBrains](https://www.jetbrains.com) for supporting us with licenses for their tools.

[](https://www.jetbrains.com)

---

## 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">}}

{{< tab tabID="installing-with-pipx" >}}

[`pipx`](https://github.com/pypa/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](https://pipx.pypa.io/stable/how-to/install-pipx.html).
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 --suffix=@1.8.4 poetry==1.8.4
poetry@1.8.4 --version
```

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

Finally, `pipx` can install any valid [pip requirement spec](https://pip.pypa.io/en/stable/cli/pip_install/), 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
```
{{< /step >}}
{{< /steps >}}

{{< /tab >}}
{{< tab tabID="installing-with-the-official-installer" >}}

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](https://install.python-poetry.org),
and is developed in [its own repository](https://github.com/python-poetry/install.python-poetry.org).
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:

```
%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 -
```
{{< /step >}}
{{< /steps >}}

{{< /tab >}}
{{< tab tabID="installing-manually" >}}

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](https://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](https://github.com/python-poetry/install.python-poetry.org)) 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 %}}

{{< /tab >}}
{{< /tabs >}}

{{% 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 = "sebastien@eustace.io"}
]
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](https://pypi.org) 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
```

{{% /note %}}

### 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](https://pip.pypa.io/en/stable/topics/local-project-installs/) 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](https://github.com/python-poetry/poetry/issues/2740).

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.

```sh
poetry add --group=build setuptools cython
```
{{% /note %}}

{{< /step >}}

{{< 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 >}}

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

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

{{< /step >}}

{{< /steps >}}

## 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">}}

{{< tab tabID="cython-pyproject" >}}

```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"
```

{{< /tab >}}

{{< tab tabID="cython-build-script" >}}

```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()
```

{{< /tab >}}

{{< tab tabID="cython-src-tree" >}}

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

{{< /tab >}}

{{< /tabs >}}

### Meson

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

{{< tab tabID="meson-pyproject" >}}

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

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

{{< /tab >}}

{{< tab tabID="meson-build-script" >}}

```py
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()
```

{{< /tab >}}

{{< /tabs >}}

### Maturin

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

{{< tab tabID="maturin-pyproject" >}}

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

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

{{< /tab >}}

{{< tab tabID="maturin-build-script" >}}

```py
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()
```

{{< /tab >}}

{{< /tabs >}}

## FAQ
### When is my build script executed?
If your project uses a build script, it is run implicitly in the following scenarios.

1. When `poetry install` is run, it is executed prior to installing the project's root package.
2. When `poetry build` is run, it is executed prior to building distributions.
3. 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        |

{{% /note %}}

* `--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](https://pypi.org).
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://git@github.com/sdispater/pendulum.git

# or alternatively:
poetry add git+ssh://git@github.com: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://git@github.com:sdispater/pendulum.git#develop
poetry add git+ssh://git@github.com: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/flask.git@1.1.1[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](https://peps.python.org/pep-0517/).
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](https://peps.python.org/pep-0440/#local-version-identifiers)
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](https://peps.python.org/pep-0440/#local-version-identifiers) 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](https://github.com/python-poetry/poetry-plugin-export).
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"
```
{{% /warning %}}

{{% 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
```
{{% /note %}}

## 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](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/).
{{% /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](https://packaging.python.org/en/latest/guides/making-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`](#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`](#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]">}}

{{< tab tabID="script-project" >}}
```toml
[project]
# ...
[project.scripts]
my-script = "my_module:main"
```
{{< /tab >}}

{{< tab tabID="script-poetry" >}}
```toml
[tool.poetry.scripts]
my-script = "my_module:main"
```
{{< /tab >}}
{{< /tabs >}}

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](https://warehouse.pypa.io/api-reference/xml-rpc.html#deprecated-methods)
and this [discussion](https://discuss.python.org/t/fastly-interfering-with-pypi-search/73597/6).
{{% /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](#add).
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](#add).
{{% /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](#install).
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](#sync).
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](#update).
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`](https://github.com/python-poetry/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 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.

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.

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 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
```

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 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](https://peps.python.org/pep-0440/)
string or a valid bump rule: `patch`, `minor`, `major`, `prepatch`, `preminor`,
`premajor`, `prerelease`.

{{% note %}}

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

{{% /note %}}

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.

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

**Markdown**
```md
[](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](#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](#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):

1. Environment variables (for example, `POETRY_VIRTUALENVS_CREATE`)
2. The local `poetry.toml` file (created with `poetry config --local`)
3. The global `config.toml` file
4. 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 %}}

{{% note %}}
For CI or container environments using [environment variable](#using-environment-variables)
to configure this might be useful.

```bash
export POETRY_INSTALLER_NO_BINARY=:all:
```
{{% /note %}}

{{% 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](https://peps.python.org/pep-0517/#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++"}'
```

{{% /note %}}

### `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](https://developer.mozilla.org/en-US/docs/Web/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`](#solvermin-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`](#solvermin-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.<name>.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.<name>.[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.<name>`

**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.<name>.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.<name>.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](https://gist.github.com), 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](https://github.com/python-poetry/poetry/discussions) and the
[kind/question label](https://github.com/python-poetry/poetry/labels/kind%2Fquestion) 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](https://github.com/python-poetry/poetry/contribute) 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][Discord] 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](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) 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
```
{{% /note %}}

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](https://mypy-lang.org/):

```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](https://pre-commit.com/) 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](https://docs.github.com/en/get-started/using-git/about-git-rebase) 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

1. 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.
2. 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.
3. Attempt to reproduce the issue with the reported Poetry version or request further clarification from the author.
4. Ensure the issue is not already resolved. Try reproducing it on the latest stable release, the latest prerelease (if
present), and the development branch.
5. 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.
6. 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](https://pypa.github.io/pipx/) makes this easy to do:

```sh
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:
```sh
pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head
```
{{% /note %}}

  [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](https://peps.python.org/pep-0508/).

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](https://peps.python.org/pep-0440/).

`==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](https://semver.org/) 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]">}}

{{< tab tabID="at-project" >}}
```toml
[project]
# ...
dependencies = [
    "django (>=4.0.0,<5.0.0)",
]
```

{{< /tab >}}

{{< tab tabID="at-poetry" >}}
```toml
[tool.poetry.dependencies]
django = "^4.0.0"
```
{{< /tab >}}
{{< /tabs >}}

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]">}}

{{< tab tabID="at-latest-project" >}}
```toml
[project]
# ...
dependencies = [
    "django (>=5.1.3,<6.0.0)",
]
```
{{< /tab >}}

{{< tab tabID="at-latest-poetry" >}}
```toml
[tool.poetry.dependencies]
django = "^5.1.3"
```
{{< /tab >}}
{{< /tabs >}}

#### 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]">}}

{{< tab tabID="git-project" >}}
```toml
[project]
# ...
dependencies = [
    "requests @ git+https://github.com/requests/requests.git",
]
```
{{< /tab >}}

{{< 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" }
```

{{< /tab >}}
{{< /tabs >}}

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/numpy.git@v0.13.2",
]
```
{{< /tab >}}

{{< 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" }
```
{{< /tab >}}
{{< /tabs >}}

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](https://pip.pypa.io/en/stable/topics/vcs-support/#url-fragments) provides.
```toml
[project]
# ...
dependencies = [
    "subdir_package @ git+https://github.com/myorg/mypackage_with_subdirs.git#subdirectory=subdir"
]
```
{{< /tab >}}

{{< 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" }
```
{{< /tab >}}
{{< /tabs >}}

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]">}}

{{< tab tabID="git-ssh-project" >}}
```toml
[project]
# ...
dependencies = [
    "pendulum @ git+ssh://git@github.com/sdispater/pendulum.git"
]
```
{{< /tab >}}

{{< tab tabID="git-ssh-poetry" >}}
```toml
[tool.poetry.dependencies]
pendulum = { git = "git@github.com/sdispater/pendulum.git" }
```
{{< /tab >}}
{{< /tabs >}}

### 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](https://www.dulwich.io/).

We fall back to legacy system git client implementation in cases where
[gitcredentials](https://git-scm.com/docs/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
```
{{% /note %}}

## `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 >}}

{{< 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]">}}

{{< tab tabID="url-project" >}}
```toml
[project]
# ...
dependencies = [
    "my-package @ https://example.com/my-package-0.1.0.tar.gz"
]
```
{{< /tab >}}

{{< 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" }
```
{{< /tab >}}
{{< /tabs >}}

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](https://www.python.org/dev/peps/pep-0508/#extras)
for a dependency as shown here.

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

{{< tab tabID="extras-project" >}}
```toml
[project]
# ...
dependencies = [
    "gunicorn[gevent] (>=20.1,<21.0)"
]
```
{{< /tab >}}

{{< tab tabID="extras-poetry" >}}
```toml
[tool.poetry.dependencies]
gunicorn = { version = "^20.1", extras = ["gevent"] }
```
{{< /tab >}}
{{< /tabs >}}

{{% 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:

```sh
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]">}}

{{< tab tabID="python-restriction-project" >}}
```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'"
]
```
{{< /tab >}}

{{< tab tabID="python-restriction-poetry" >}}

```toml
[tool.poetry.dependencies]
tomli = { version = "^2.0.1", python = "<3.11" }
pathlib2 = { version = "^2.2", python = "^3.9" }
```
{{< /tab >}}
{{< /tabs >}}

## Using environment markers

If you need more complex install conditions for your dependencies,
Poetry supports [environment markers](https://www.python.org/dev/peps/pep-0508/#environment-markers):

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

{{< tab tabID="markers-project" >}}
```toml
[project]
# ...
dependencies = [
    "pathlib2 (>=2.2,<3.0) ; python_version <= '3.4' or sys_platform == 'win32'"
]
```
{{< /tab >}}

{{< 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'" }
```
{{< /tab >}}
{{< /tabs >}}

### `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.

{{% /warning %}}

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]">}}

{{< tab tabID="multiple-constraints-project" >}}
```toml
[project]
# ...
dependencies = [
    "foo (<=1.9) ; python_version >= '3.6' and python_version < '3.8'",
    "foo (>=2.0,<3.0) ; python_version >= '3.8'"
]
```
{{< /tab >}}

{{< tab tabID="multiple-constraints-poetry" >}}
```toml
[tool.poetry.dependencies]
foo = [
    {version = "<=1.9", python = ">=3.6,<3.8"},
    {version = "^2.0", python = ">=3.8"}
]
```
{{< /tab >}}
{{< /tabs >}}

{{% 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](https://peps.python.org/pep-0440/#final-releases).

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](https://semver.org) 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](https://semver.org).

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](https://tox.wiki/en/3.27.1/config.html#conf-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](https://tox.wiki/en/latest/config.html#passenv) 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`](https://github.com/cjolowicz/nox-poetry) package to install locked versions of
dependencies specified in `poetry.lock` into [Nox](https://nox.thea.codes/en/stable/) 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.:

```
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](https://peps.python.org/pep-0440), 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:

1. Install 3rd party dependencies.
2. 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](https://packaging.python.org/en/latest/specifications/pyproject-toml/#declaring-project-metadata-the-project-table).

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">}}

{{< tab tabID="migrate-pep621-old" >}}

```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"
```

{{< /tab >}}

{{< tab tabID="migrate-pep621-new-static" >}}

```toml
[project]
name = "foobar"
version = "0.1.0"
description = ""
authors = [
    { name = "Baz Qux", email = "baz.qux@example.com" }
]
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"
```

{{< /tab >}}

{{< tab tabID="migrate-pep621-new-static" >}}

```toml
[project]
name = "foobar"
version = "0.1.0"
description = ""
authors = [
    { name = "Baz Qux", email = "baz.qux@example.com" }
]
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"
```

{{< /tab >}}

{{< /tabs >}}

{{% note %}}
- 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

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

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

The script is hosted on [Vercel](https://vercel.com/) 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](https://github.com/pypa/virtualenv/issues/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](https://bugs.launchpad.net/ubuntu/+source/python3.10/+bug/1940705).
See also [pypa/get-pip#124](https://github.com/pypa/get-pip/issues/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`.