Commands | Documentation | Poetry (original) (raw)

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 #

about #

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

add #

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

If you do not specify a version constraint, poetry will choose a suitable one based on the available package versions.

poetry add requests pendulum

You can also specify a constraint when adding a package:

# 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

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:

poetry add pendulum@latest

You can also add git dependencies:

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

or use ssh instead of https:

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:

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:

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

You can also add a local directory or file:

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.

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.

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

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

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.

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

poetry add mkdocs --group docs

See Dependency groups for more information about dependency groups.

Options #

build #

The build command builds the source and wheels archives.

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

Options #

Note

When using --local-version, the identifier must be PEP 440compliant. 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.

Warning

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

See PEP 440 for more information.

cache #

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

cache clear #

The cache clear command removes packages from a cached repository.

For example, to clear the whole cache of packages from the PyPI repository, run:

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:

poetry cache clear pypi:requests:2.24.0

cache list #

The cache list command lists Poetry’s available caches.

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 for more information.

Options #

config #

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

Usage #

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 for all available settings.

Warning

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

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.

Options #

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

env info #

The env info command displays information about the current environment.

Options #

env list #

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

Options #

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.

Arguments #

Options #

env use #

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

Arguments #

export #

Warning

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

See Using plugins for information on how to install a plugin. As described in Project plugins, you can also define in your pyproject.toml that the plugin is required for the development of your project:

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

Note

The export command is also available as a pre-commit hook. See pre-commit hooks for more information.

help #

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

To display global help:

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

Note

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

For instance:

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.

Options #

install #

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

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 installbecause poetry sync will normally not work well in these cases.

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.

poetry install --without test,docs

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

poetry install --with test,docs

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

poetry install --all-groups

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

poetry install --only test,docs

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

poetry install --only-root

See 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 for more info). Pass --all-extras to install all defined extras for a project.

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:

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:

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

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

poetry install --no-directory

This is mainly useful for caching in CI or when building Docker images. See the FAQ entry 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:

Options #

Note

When --only is specified, --with and --without options are ignored.

list #

The list command displays all the available Poetry commands.

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 --lockor poetry lock --regenerate, which normally produce the same result. This command is also available as a pre-commit hook. See pre-commit hooks for more information.

Options #

new #

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

will create a folder as follows:

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:

poetry new my-folder --name my-package

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

poetry new --flat my-package

That will create a folder structure as follows:

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

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

poetry new --name my.package my-package

will create the following structure:

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

Options #

publish #

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

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

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

Options #

python #

The python namespace groups subcommands to manage Python versions.

Warning

This is an experimental feature, and can change behaviour in upcoming releases.

Introduced in 2.1.0

python install #

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

poetry python install <PYTHON_VERSION>

Options #

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.

Options #

python remove #

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

poetry python remove <PYTHON_VERSION>

Options #

remove #

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

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

poetry remove mkdocs --group docs

See Dependency groups for more information about dependency groups.

Options #

run #

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

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

So, if you have a script defined like this:

[project] [tool.poetry] 

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

You can execute it like so:

Note that this command has no option.

search #

This command searches for packages on a remote index.

poetry search requests pendulum

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 in yourconfiguration directory.

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 andInstalling Poetry for more information.

self add #

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

Note

The self add command works exactly like the add command. However, 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.

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

poetry self add poetry-plugin-export

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

poetry self add poetry-core@latest

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

poetry self add artifacts-keyring

Options #

self install #

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

Note

The self install command works similar to the install command. However, it is different in that the packages managed are for Poetry’s runtime environment.

Options #

self lock #

The self lock command reads this Poetry installation’s system pyproject.toml file. The system dependencies are locked in the corresponding poetry.lock file.

Options #

self remove #

The self remove command removes an installed addon package.

poetry self remove poetry-plugin-export

Options #

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.

Options #

self show plugins #

The self show plugins command lists all the currently installed 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 similar to the sync command. However, it is different in that the packages managed are for Poetry’s runtime environment.

Options #

self update #

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

Note

The self update command works exactly like the update command. However, is different in that the packages managed are for Poetry’s runtime environment.

Options #

shell #

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

show #

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

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

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 #

Note

When --only is specified, --with and --without options are ignored.

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:

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:

poetry source add --priority=explicit pypi

Options #

source show #

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

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

poetry source show pypi-test

Note

This command will only show sources configured via the pyproject.tomland does not include the implicit default PyPI.

source remove #

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

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.

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.

poetry sync --without test,docs

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

poetry sync --with test,docs

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

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

poetry sync --only test,docs

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

See 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 for more info). Pass --all-extras to install all defined extras for a project.

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

Any extras not specified will always be removed.

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

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

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

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

poetry sync --no-directory

This is mainly useful for caching in CI or when building Docker images. See the FAQ entry 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:

Options #

Note

When --only is specified, --with and --without options are ignored.

update #

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

This will resolve all dependencies of the project and write the exact versions into poetry.lock.

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

poetry update requests toml

Note that this will not update versions for dependencies outside theirversion constraintsspecified 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 #

Note

When --only is specified, --with and --without options are ignored.

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 440string 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 seehere.

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 #