Commands Reference

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the Python Reference bibliography.

This page lists every command of Poetry 2.5.1 (with poetry-plugin-export 1.10.1 providing export) and every argument and option of each, taken from the --help output of that release on 2026-10-22 (CPython 3.14.6, Linux). The tables quote the help text; the notes under them add what the help does not say. The other Poetry pages explain the commands in context.

Global options

These work with every command, before or after the command name.

Option Meaning

-h, --help

Help for the command (poetry help <command> does the same and also works for run).

-q, --quiet

No output.

-V, --version

Poetry’s version: Poetry (version 2.5.1).

--ansi, --no-ansi

Force or disable colours.

-n, --no-interaction

Never ask a question; use it in CI and scripts.

--no-plugins

Do not load plugins (for example to rule a plugin out when debugging).

--no-cache

Ignore Poetry’s caches for this command, as if they were cold; nothing is deleted.

-P, --project=PROJECT

Use the pyproject.toml in another directory, resolving arguments against the current directory (2.0).

-C, --directory=DIRECTORY

Change to that directory first, then run (since 2.0 it really switches directory).

-v, -vv, -vvv

More output; -vvv shows debug output such as every HTTP request.

The SHELL_VERBOSITY environment variable sets the same levels without touching the command line, which helps in CI: -1 is -q, 0 the default, 1 to 3 are -v to -vvv. With SHELL_VERBOSITY=3, poetry version first printed Loading configuration file …/config.toml and the sources it registered.

cd /tmp && poetry -P …/birdtally-report version
poetry -C /tmp version
birdtally-report 0.1.0

Poetry could not find a pyproject.toml file in /tmp or its parents

Source: Poetry CLI: Global options.

Exit codes

In every case tried, Poetry exited with 0 on success and 1 on an error it reported itself: an unknown command or option, an invalid setting, a failed resolution, a validation error, a missing project. poetry run returns the exit code of the program it ran.

poetry nosuch;                                  echo "exit=$?"
poetry add --bogus x;                           echo "exit=$?"
poetry show nosuchpkg;                          echo "exit=$?"
poetry run python -c "raise SystemExit(3)";     echo "exit=$?"
The requested command nosuch does not exist.

Documentation: https://python-poetry.org/docs/cli/
exit=1

The option "--bogus" does not exist
exit=1

Package nosuchpkg not found
exit=1
exit=3

Source: Poetry CLI: run, Poetry CLI: Global options.

Command index

Area Commands

Project

new, init, check, version

Dependencies

add, remove, show, search

Lock and install

lock, install, sync, update, export

Running

run, env activate, env info, env list, env remove, env use

Pythons (experimental)

python install, python list, python remove

Packaging

build, publish

Configuration and sources

config, source add, source show, source remove

Caches and debugging

cache clear, cache list, debug info, debug resolve, debug tags

Poetry itself

self add, self remove, self install, self sync, self lock, self show, self show plugins, self update, about, help, list, completions

Plugins

Plugin commands

Commands

new

Usage: poetry new [options] [--] <path>

Argument or option Meaning

path

The path to create the project at.

-i, --interactive

Allow interactive specification of project configuration.

--name=NAME

Set the resulting package name.

--src

Use the src layout for the project. Deprecated: This is the default option now.

--flat

Use the flat layout for the project.

--readme=README

Specify the readme file format. Default is md.

--description=DESCRIPTION

Description of the package.

--author=AUTHOR

Author name of the package.

--python=PYTHON

Compatible Python versions.

--dependency=DEPENDENCY

Package to require, with an optional version constraint, for example requests:^2.10.0 or requests=2.11.1. (multiple values allowed)

--dev-dependency=DEV-DEPENDENCY

Package to require for development, with an optional version constraint, for example requests:^2.10.0 or requests=2.11.1. (multiple values allowed)

-l, --license=LICENSE

License of the package.

Example: poetry new --name birdtally birdtally. Details: Basic Usage & Project Setup. Since 2.0 the src layout is the default (--src is deprecated) and -i asks for the fields interactively.

init

Usage: poetry init [options]

Argument or option Meaning

--name=NAME

Name of the package.

--description=DESCRIPTION

Description of the package.

--author=AUTHOR

Author name of the package.

--python=PYTHON

Compatible Python versions.

--dependency=DEPENDENCY

Package to require, with an optional version constraint, for example requests:^2.10.0 or requests=2.11.1. (multiple values allowed)

--dev-dependency=DEV-DEPENDENCY

Package to require for development, with an optional version constraint, for example requests:^2.10.0 or requests=2.11.1. (multiple values allowed)

-l, --license=LICENSE

License of the package.

Example: poetry init -n --name birdtally --python ">=3.10". Writes pyproject.toml in an existing directory, interactively unless -n. Details: Basic Usage & Project Setup.

add

Usage: poetry add [options] [--] <name>...

Argument or option Meaning

name

The packages to add.

-G, --group=GROUP

The group to add the dependency to. [default: "main"]

-D, --dev

Add as a development dependency. (shortcut for -G dev)

-e, --editable

Add vcs/path dependencies as editable.

-E, --extras=EXTRAS

Extras to activate for the dependency. (multiple values allowed)

--optional=OPTIONAL

Add as an optional dependency to an extra.

--python=PYTHON

Python version for which the dependency must be installed.

--platform=PLATFORM

Platforms for which the dependency must be installed.

--markers=MARKERS

Environment markers which describe when the dependency should be installed.

--source=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 operations (only update the lockfile).

Example: poetry add "rich>=13" --optional=pretty. Constraint forms (^, ~, @latest, git, path and URL) are on Dependency Specification; groups and --optional on Managing Dependencies & Groups. Since 2.0, --optional takes the name of the extra.

remove

Usage: poetry remove [options] [--] <packages>...

Argument or option Meaning

packages

The packages to remove.

-G, --group=GROUP

The group to remove the dependency from.

-D, --dev

Remove a package from the development dependencies. (shortcut for -G dev)

--dry-run

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

--lock

Do not perform operations (only update the lockfile).

Example: poetry remove --group test pytest-mock. Details: Managing Dependencies & Groups.

show

Usage: poetry show [options] [--] [<package>]

Argument or option Meaning

package

The package to inspect

--without=WITHOUT

The dependency groups to ignore. (multiple values allowed)

--with=WITH

The optional dependency groups to include. (multiple values allowed)

--only=ONLY

The only dependency groups to include. (multiple values allowed)

-t, --tree

List the dependencies as a tree.

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

-l, --latest

Show the latest version.

-o, --outdated

Show the latest version but only for packages that are outdated.

-a, --all

Show all packages (even those not compatible with current system).

-T, --top-level

Show only top-level dependencies.

--no-truncate

Do not truncate the output based on the terminal width.

-f, --format=FORMAT

Specify the output format (json or text). Default is text. json cannot be combined with the --tree option. [default: "text"]

Example: poetry show --tree --only main. Details: Managing Dependencies & Groups.

install

Usage: poetry install [options]

Argument or option Meaning

--without=WITHOUT

The dependency groups to ignore. (multiple values allowed)

--with=WITH

The optional dependency groups to include. (multiple values allowed)

--only=ONLY

The only dependency groups to include. (multiple values allowed)

--sync

Synchronize the environment with the locked packages and the specified groups. (Deprecated)

--no-root

Do not install the root package (the current project).

--no-directory

Do not install any directory path dependencies; useful to install dependencies without source code, e.g. for caching of Docker layers)

--dry-run

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

-E, --extras=EXTRAS

Extra sets of dependencies to install. (multiple values allowed)

--all-extras

Install all extra dependencies.

--all-groups

Install dependencies from all groups.

--only-root

Exclude all dependencies.

--compile

Compile Python source files to bytecode.

Example: poetry install --with docs --extras pretty. --sync is deprecated since 2.0 in favour of poetry sync. Details: Lock File, Install, Update & Sync.

sync

Usage: poetry sync [options]

Argument or option Meaning

--without=WITHOUT

The dependency groups to ignore. (multiple values allowed)

--with=WITH

The optional dependency groups to include. (multiple values allowed)

--only=ONLY

The only dependency groups to include. (multiple values allowed)

--no-root

Do not install the root package (the current project).

--no-directory

Do not install any directory path dependencies; useful to install dependencies without source code, e.g. for caching of Docker layers)

--dry-run

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

-E, --extras=EXTRAS

Extra sets of dependencies to install. (multiple values allowed)

--all-extras

Install all extra dependencies.

--all-groups

Install dependencies from all groups.

--only-root

Exclude all dependencies.

--compile

Compile Python source files to bytecode.

Example: poetry sync --only main,test. Added in 2.0 (replacing install --sync). Removes everything not in the lock file for the selected groups and extras.

lock

Usage: poetry lock [options]

Argument or option Meaning

--regenerate

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

Example: poetry lock --regenerate. Since 2.0, poetry lock keeps the locked versions where it can (the old --no-update behaviour); --regenerate resolves from scratch.

update

Usage: poetry update [options] [--] [<packages>...]

Argument or option Meaning

packages

The packages to update

--without=WITHOUT

The dependency groups to ignore. (multiple values allowed)

--with=WITH

The optional dependency groups to include. (multiple values allowed)

--only=ONLY

The only dependency groups to include. (multiple values allowed)

--sync

Synchronize the environment with the locked packages and the specified groups.

--dry-run

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

--lock

Do not perform operations (only update the lockfile).

Example: poetry update rich --dry-run. Updates within the constraints of pyproject.toml; to move past them use poetry add <name>@latest. Unlike install --sync (deprecated since 2.0 in favour of poetry sync), update --sync (added in 1.8) is not deprecated in Poetry 2.5.1: its help text, the CLI documentation and the source carry no deprecation label or warning. It updates the lock and then removes what the lock and the selected groups no longer need, like poetry update followed by poetry sync.

run

Usage: poetry run [options] [--] <args>...

Argument or option Meaning

args

The command and arguments/options to run.

Example: poetry run pytest -q. Exits with the exit code of the command it runs. Everything after run belongs to that command, so poetry run --help answers Command not found: --help; use poetry help run. The scripts in [project.scripts] can be run by name.

build

Usage: poetry build [options]

Argument or option Meaning

-f, --format=FORMAT

Limit the format to either sdist or wheel.

--clean

Clean output directory before building.

-l, --local-version=LOCAL-VERSION

Add or replace a local version label to the build. (Deprecated)

-o, --output=OUTPUT

Set output directory for build artifacts. Default is dist. [default: "dist"]

-c, --config-settings=CONFIG-SETTINGS

Provide config settings that should be passed to backend in <key>=<value> format. (multiple values allowed)

Example: poetry build --format wheel --clean. --local-version (2.0) is already deprecated; --config-settings is passed to the build back end (PEP 517). Building and publishing: Publishing with Poetry.

publish

Usage: poetry publish [options]

Argument or option Meaning

-r, --repository=REPOSITORY

The repository to publish the package to.

-u, --username=USERNAME

The username to access the repository.

-p, --password=PASSWORD

The password to access the repository.

--cert=CERT

Certificate authority to access the repository.

--client-cert=CLIENT-CERT

Client certificate to access the repository.

--dist-dir=DIST-DIR

Dist directory where built artifact are stored. Default is dist. [default: "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.

Example: poetry publish --repository birdwatch-pub --dry-run. Never put --password on a shared command line; use POETRY_PYPI_TOKEN_<NAME> or POETRY_HTTP_BASIC_<NAME>_PASSWORD. Details: Publishing with Poetry.

check

Usage: poetry check [options]

Argument or option Meaning

--lock

Checks that poetry.lock exists for the current version of pyproject.toml.

--strict

Fail if check reports warnings.

Example: poetry check --lock --strict. Validates pyproject.toml and that poetry.lock matches it; a stale lock file fails with exit code 1 and Error: pyproject.toml changed significantly since poetry.lock was last generated. …. --lock (1.6.0, replacing poetry lock --check) also fails when there is no lock file. Prints All set! and exits 0 when everything is fine.

config

Usage: poetry config [options] [--] [<key> [<value>...]]

Argument or option Meaning

key

Setting key.

value

Setting value.

--list

List configuration settings.

--unset

Unset configuration setting.

--local

Set/Get from the project’s local configuration.

--migrate

Migrate outdated configuration settings.

Example: poetry config --local virtualenvs.in-project true. Every setting: Configuration.

source add

Usage: poetry source add [options] [--] <name> [<url>]

Argument or option Meaning

name

Source repository name.

url

Source repository URL. Required, except for PyPI, for which it is not allowed.

-p, --priority=PRIORITY

Set the priority of this source. One of: primary, supplemental, explicit. Defaults to primary, but will switch to supplemental in a later release.

Example: poetry source add --priority=explicit birdwatch http://127.0.0.1:8082/simple/. Priorities and credentials: Repositories & Package Sources.

source show

Usage: poetry source show [options] [--] [<source>...]

Argument or option Meaning

source

Source(s) to show information for. Defaults to showing all sources.

Example: poetry source show birdwatch.

source remove

Usage: poetry source remove [options] [--] <name>

Argument or option Meaning

name

Source repository name.

Example: poetry source remove birdwatch.

env activate

Usage: poetry env activate [options]

Example: eval "$(poetry env activate)".

env info

Usage: poetry env info [options]

Argument or option Meaning

-p, --path

Only display the environment’s path.

-e, --executable

Only display the environment’s python executable path.

Example: poetry env info --path.

env list

Usage: poetry env list [options]

Argument or option Meaning

--full-path

Output the full paths of the virtualenvs.

Example: poetry env list --full-path.

env remove

Usage: poetry env remove [options] [--] [<python>...]

Argument or option Meaning

python

The python executables associated with, or names of the virtual environments which are to be removed.

--all

Remove all managed virtual environments associated with the project.

Example: poetry env remove --all.

env use

Usage: poetry env use [options] [--] <python>

Argument or option Meaning

python

The python executable to use.

Example: poetry env use 3.14. The env commands: Managing Environments. env activate replaced poetry shell (moved to poetry-plugin-shell) in 2.0.

python install

Usage: poetry python install [options] [--] <python>

Argument or option Meaning

python

The python version to install.

-c, --clean

Clean up installation if check fails.

-t, --free-threaded

Use free-threaded version if available.

-i, --implementation=IMPLEMENTATION

Python implementation to use. (cpython, pypy) [default: "cpython"]

-r, --reinstall

Reinstall if installation already exists.

Example: poetry python install --free-threaded 3.14.

python list

Usage: poetry python list [options] [--] [<version>]

Argument or option Meaning

version

Python version to search for.

-a, --all

List all versions, including those available for download.

-t, --free-threaded

List only free-threaded Python versions.

-i, --implementation=IMPLEMENTATION

Python implementation to search for.

-m, --managed

List only Poetry managed Python versions.

Example: poetry python list --managed.

python remove

Usage: poetry python remove [options] [--] <python>...

Argument or option Meaning

python

The python version to remove.

-t, --free-threaded

Use free-threaded version if available.

-i, --implementation=IMPLEMENTATION

Python implementation to use. (cpython, pypy) [default: "cpython"]

Example: poetry python remove 3.13.11. Experimental since 2.1; see Managing Environments.

version

Usage: poetry version [options] [--] [<version>]

Argument or option Meaning

version

The version number or the rule to update the version.

-s, --short

Output the version number only

--dry-run

Do not update pyproject.toml file

--next-phase

Increment the phase of the current version

Example: poetry version minor --dry-run. Bump rules: major, minor, patch, premajor, preminor, prepatch, prerelease; anything else must be a PEP 440 version. Releases and versioning: Versioning & Release Management.

cache clear

Usage: poetry cache clear [options] [--] [<cache>]

Argument or option Meaning

cache

The name of the cache to clear.

--all

Clear all entries in the cache.

Example: poetry cache clear PyPI --all.

cache list

Usage: poetry cache list [options]

Example: poetry cache list. cache clear <name> --all deletes a source’s whole cache; cache clear <name>:<package>:<version> one entry.

debug info

Usage: poetry debug info [options]

Example: poetry debug info.

debug resolve

Usage: poetry debug resolve [options] [--] [<package>...]

Argument or option Meaning

package

The packages to resolve.

-E, --extras=EXTRAS

Extras to activate for the dependency. (multiple values allowed)

--python=PYTHON

Python version(s) to use for resolution.

--tree

Display the dependency tree.

--install

Show what would be installed for the current system.

Example: poetry debug resolve --tree attrs.

debug tags

Usage: poetry debug tags [options]

Example: poetry debug tags. debug tags lists the wheel tags the project’s environment accepts, most preferred first.

search

Usage: poetry search [options] [--] <tokens>...

Argument or option Meaning

tokens

The tokens to search for.

Example: poetry search birdtally. PyPI no longer supports searching without a browser, so against PyPI this only finds exact names (No matching packages were found. otherwise).

export

Usage: poetry export [options]

Argument or option Meaning

-f, --format=FORMAT

Format to export to: constraints.txt, requirements.txt, pylock.toml [default: "requirements.txt"]

-o, --output=OUTPUT

The name of the output file.

--without-hashes

Exclude hashes from the exported file.

--without-urls

Exclude source repository urls from the exported file.

--dev

Include development dependencies. (Deprecated)

--all-groups

Include all dependency groups

--with=WITH

The optional and non-optional dependency groups to include. By default, only the main dependencies are included. (multiple values allowed)

--only=ONLY

The only dependency groups to include. (multiple values allowed)

--without=WITHOUT

The dependency groups to ignore. (Deprecated) (multiple values allowed)

-E, --extras=EXTRAS

Extra sets of dependencies to include. (multiple values allowed)

--all-extras

Include all sets of extra dependencies.

--with-credentials

Include credentials for extra indices.

Example: poetry export -f requirements.txt -o requirements.txt. Provided by poetry-plugin-export, which is no longer bundled since Poetry 2.0. Details: Exporting Requirements & Bundling.

self add

Usage: poetry self add [options] [--] <name>...

Argument or option Meaning

name

The packages to add.

-e, --editable

Add vcs/path dependencies as editable.

-E, --extras=EXTRAS

Extras to activate for the dependency. (multiple values allowed)

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

Example: poetry self add poetry-plugin-export.

self remove

Usage: poetry self remove [options] [--] <packages>...

Argument or option Meaning

packages

The packages to remove.

--dry-run

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

Example: poetry self remove poetry-plugin-shell.

self install

Usage: poetry self install [options]

Argument or option Meaning

--sync

Synchronize the environment with the locked packages and the specified groups. (Deprecated)

--dry-run

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

Example: poetry self install --dry-run.

self sync

Usage: poetry self sync [options]

Argument or option Meaning

--dry-run

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

Example: poetry self sync.

self lock

Usage: poetry self lock [options]

Argument or option Meaning

--regenerate

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

Example: poetry self lock.

self show

Usage: poetry self show [options] [--] [<package>]

Argument or option Meaning

package

The package to inspect

--addons

List only add-on packages installed.

-t, --tree

List the dependencies as a tree.

-l, --latest

Show the latest version.

-o, --outdated

Show the latest version but only for packages that are outdated.

-f, --format=FORMAT

Specify the output format (json or text). Default is text. json cannot be combined with the --tree option. [default: "text"]

Example: poetry self show --addons.

self show plugins

Usage: poetry self show plugins [options]

Example: poetry self show plugins.

self update

Usage: poetry self update [options] [--] [<version>]

Argument or option Meaning

version

The version to update to. [default: "latest"]

--preview

Allow the installation of pre-release versions.

--dry-run

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

Example: poetry self update 2.5.1. The self commands work on Poetry’s own environment, with its own pyproject.toml and lock file; see Installation & Self-Management. With pipx, update with pipx upgrade poetry instead.

about

Usage: poetry about [options]

Example: poetry about.

help

Usage: poetry help [options] [--] [<command_name>]

Argument or option Meaning

command_name

The command name [default: "help"]

Example: poetry help install.

list

Usage: poetry list [options] [--] [<namespace>]

Argument or option Meaning

namespace

The namespace name

Example: poetry list env. poetry list <namespace> shows one group, for example poetry list env.

completions

Usage: poetry completions [options] [--] [<shell>]

Argument or option Meaning

shell

The shell to generate the scripts for.

--alias=ALIAS

Alias for the current command. (multiple values allowed)

Example: poetry completions bash > ~/.local/share/bash-completion/completions/poetry. Poetry prints a completion script for bash, zsh or fish; see the installation documentation for where each shell expects it.

Plugin commands

Command Provided by

poetry export

poetry-plugin-export 1.10.1 (listed above, because it was installed here); see Exporting Requirements & Bundling.

poetry shell

poetry-plugin-shell 1.0.1: starts a subshell with the environment activated; leave it with exit. The plugin’s maintainers are looking for help; prefer poetry env activate.

poetry bundle venv

poetry-plugin-bundle 1.8.0; see Exporting Requirements & Bundling.

Source: Poetry CLI: shell, poetry-plugin-shell.

Examples of output

poetry version
poetry version --short
poetry version minor --dry-run
poetry version prerelease --dry-run
poetry version bogus
birdtally-report 0.1.0
0.1.0
Bumping version from 0.1.0 to 0.2.0
Bumping version from 0.1.0 to 0.1.1a0

Invalid PEP 440 version: 'bogus'
poetry show --latest
poetry debug resolve birdtally
poetry debug resolve --tree attrs
attrs     26.1.0 26.1.0 Classes Without Boilerplate
birdtally 0.1.0  0.1.0  Tally bird-survey sightings from CSV files.

Could not find a matching version of package birdtally
Resolving dependencies...

Resolution results:

attrs 26.1.0 Classes Without Boilerplate

Note the second command: debug resolve reported birdtally, which lives only on the explicit birdwatch source, as not found, while poetry lock resolves it through the project’s source constraint. Check such packages with poetry lock or poetry show.

Source: Poetry CLI: version, Poetry CLI: show, Poetry CLI: debug resolve.

Compared with pip

pip has no project commands (new, init, add, lock, version, build, publish); pip install, pip uninstall, pip list, pip show, pip lock (experimental), pip config, pip cache and pip debug are the closest counterparts of install/sync, remove, show, lock, config, cache and debug info/debug tags. See the Choosing & Migrating mapping table and pip: Running pip & General Options.

References