Commands

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.
• --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 - plugin: Disables plugins.
• --no-cache: Disables Poetry source caches.
• --directory = directory ( -C ): Theworking 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 ordirectory specified using --directory option if used .

new

This command will help you kickstart your new Python project by creating
a directory structure suitable for most projects.

will create a folder as follows:

my-package
├── pyproject.toml
├ ─ ─ readme.md 
├── my_package
│   └── __init__.py
└ ─ ─ test 
     └ ─ ─ _ _ init__.py 

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

poetrynew my - folder --name my - package 

If you want to use a src folder ,you isuse can use the--src option:

poetrynew --src my-package

That will create a folder structure as follows:

my-package
├── pyproject.toml
├ ─ ─ readme.md 
├── src
│   └── my_package
│        └ ─ ─ _ _ init__.py 
└ ─ ─ test 
     └ ─ ─ _ _ init__.py 

The--name option isis issmart enough to detect namespace package andcreate
the required structure for you .

poetrynew --src --name my.package my-package

will create the following structure:

my-package
├── pyproject.toml
├ ─ ─ readme.md 
├── src
│   └── my
│       └── package
│            └ ─ ─ _ _ init__.py 
└ ─ ─ test 
     └ ─ ─ _ _ init__.py 

option

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

init

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

It isask will interactively ask you to fill in the field ,while using some smart default .

option

• --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 formatfoo:1.0.0.
• --dev - dependency: Development requirements,see --dependency.

install

Theinstall command isreads read thepyproject.toml file from the current project,
resolves the dependencies,and installs them.

note

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

If there isa 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 isno poetry.lock file ,Poetry iscreate will create one after dependency resolution .

If you want to exclude one ormore dependency group for the installation ,you isuse can use
the--without option .

poetry isinstall install --without test ,doc 

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

poetryinstall --with test,docs

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

poetry isinstall install --all - group 

It is’s ’s also possible to only install specific dependency group by using theonly option .

poetryinstall --only test,docs

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

poetry isinstall install --only - root 

See dependency group for more information
about dependency group .

You isspecify can also specify the extra you want instal
by pass the-E|--extra option ( See Extras for more info ) .
Pass--all - extra to install all defined extras for a project.

poetryinstall --extra "mysql pgsql"
poetryinstall -E mysql -E pgsql
poetryinstall --all - extra

Any extra not specify will always be remove .

poetryinstall --extra "A B"  # C  isremoved

By defaultpoetry will install your project ’s package every time you runinstall:

$ poetryinstall
instal dependency from lock file 

No dependency to install  orupdate 

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

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

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

poetryinstall --no - directory

This ismainly useful for caching in CI orwhen building Docker images. See the FAQ entry for more information on this option .

By defaultpoetry 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:

option

• --without: Thedependency groups to ignore.
• --with: Theoptional dependency groups to include.
• --only: Theonly dependency groups to include.
• --only - root: Install only the root project,exclude all dependencies.
• --sync: Synchronize the environment with the locked packages andthe specified groups. (Deprecated,use poetry issync 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 operation but do not execute anything ( implicitly enable--verbose) .
• --extra (-E): Features to install (multiple values allowed) .
• --all - extra: install all extra feature ( conflict with--extra) .
• --all-groups: Install dependencies from all groups (conflicts with --only,--with,and --without) .
• --compile: compile Python source file to bytecode .

note

When--only isspecified,--with and--without options are ignored.

sync

Thesync command makes sure that the project’s environment isin sync with the poetry.lock file .
It issimilar to poetryinstall but it additionally removes packages that are not tracked in the lock file .

If there isa 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 isno poetry.lock file ,Poetry iscreate will create one after dependency resolution .

If you want to exclude one ormore dependency group for the installation ,you isuse can use
the--without option .

poetry issync sync --without test,docs

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

poetry issync sync --with test,docs

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

It is’s ’s also possible to only install specific dependency group by using theonly option .

poetry issync sync --only test,docs

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

See dependency group for more information
about dependency group .

You isspecify can also specify the extra you want instal
by pass the-E|--extra option ( See Extras for more info ) .
Pass--all - extra to install all defined extras for a project.

poetry issync sync --extra "mysql pgsql"
poetry issync sync -E mysql -E pgsql
poetry issync sync --all - extra

Any extra not specify will always be remove .

poetry issync sync --extra "A B"  # C  isremoved

By defaultpoetry will install your project ’s package every time you runsync:

$ poetry issync sync
instal dependency from lock file 

No dependency to install  orupdate 

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

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

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

poetry issync sync --no - directory

This ismainly useful for caching in CI orwhen building Docker images. See the FAQ entry for more information on this option .

By defaultpoetry 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:

option

• --without: Thedependency groups to ignore.
• --with: Theoptional dependency groups to include.
• --only: Theonly 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 operation but do not execute anything ( implicitly enable--verbose) .
• --extra (-E): Features to install (multiple values allowed) .
• --all - extra: install all extra feature ( conflict with--extra) .
• --all-groups: Install dependencies from all groups (conflicts with --only,--with,and --without) .
• --compile: compile Python source file to bytecode .

note

When--only isspecified,--with and--without options are ignored.

update

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

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

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

poetryupdate requests toml

note that this will not update versions for dependencies outside their
version constraints
specified in the pyproject.toml file .
In other terms,poetryupdate foo will be a no – op if the version constraint
specify forfoo is~2.3 or2.3 and2.4 isavailable.
In order for foo to be updated,you must update the constraint,for example ^2.3.
You can do this using the add command .

option

• --without: Thedependency groups to ignore.
• --with: Theoptional dependency groups to include.
• --only: Theonly 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 andthe specified groups.

note

When--only isspecified,--with and--without options are ignored.

add

Theadd command adds required packages to your pyproject.toml andinstalls them.

If you do not specify a version constraint ,
poetryis choose will choose a suitable one base on the available package version .

poetryis add addrequests pendulum

You can also specify a constraint when adding a package:

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

# Allow >=2.0.5,<2.1.0 versions
poetryis add addpendulum@~2.0.5

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

# Allow only 2.0.5 version
poetryis add addpendulum==2.0.5

If you try to add a package that isalready 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 isuse can usethe special latest constraint :

poetryis add add pendulum@latest 

You can also add git dependencies:

poetryis add addgit+https://github.com/sdispater/pendulum.git

or use ssh instead of https:

poetryis add addgit+ssh://git@github.com/sdispater/pendulum.git

#  oralternatively:
poetryis add addgit+ssh://git@github.com:sdispater/pendulum.git

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

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

#  orusing SSH instead :
poetryis add addgit+ssh://git@github.com:sdispater/pendulum.git#develop
poetryis add addgit+ssh://git@github.com:sdispater/pendulum.git#2.0.5

or reference a subdirectory :

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

You is add can also add a local directory orfile :

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

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

poetryis add add--editable ./my-package/
poetryis add 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

Thedevelop attribute isa Poetry-specific feature,so it isnot included in the package distribution metadata.
In other words,it isonly 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:

poetryis add add"requests[security,socks]"
poetryis add add"requests[security,socks]~=2.22.0"
poetryis add 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 issuggested 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 isuse can usethe --group (-G) option:

poetryis add addmkdocs --group docs

See dependency group for more information
about dependency group .

option

• --group (-G): Thegroup to add the dependency to.
• --dev ( -D ): add package as development dependency . ( shortcut for-G dev)
• --editable ( -e ): add vcs / path dependency as editable .
• --extra (-E): Extras to activate for the dependency . ( multiple values is allowed allow )
• --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.
• --marker: Environment markers which describe when the dependency should be installed.
• --source: Name of the source to use to install the package.
• --allow-prereleases: accept prerelease .
• --dry - run: output the operation but do not execute anything ( implicitly enable--verbose) .
• --lock: Do not perform install (only update the lockfile) .

remove

Theremove 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 isuse can usethe --group (-G) option:

poetryremove mkdocs --group docs

See dependency group for more information
about dependency group .

option

• --group (-G): Thegroup 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) .

show

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

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

poetryshow pendulum

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

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

require by 
 - calendar requires >=1.4.0

option

• --without: Thedependency groups to ignore.
• --why: Whenshowing the full list,or a --tree for a single package,display whether they are a direct dependency orrequired by other packages.
• --with: Theoptional dependency groups to include.
• --only: Theonly 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 define package .

note

When--only isspecified,--with and--without options are ignored.

build

Thebuild command builds the source andwheels archives.

note that,at the moment,only pure python wheels are supported.

option

• --format (-f): limit the format to eitherwheel orsdist.
• --clean: clean output directory before building .
• --local-version (-l): Add orreplace a local version label to the build.
• --output (-o): Set output directory for build artifacts. Default isdist.

note

Whenusing

--local-version

,the identifier must be

pep 440

compliant. This isuseful for adding build numbers,platform specificities etc. for private packages.

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 .

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 isthe first time it issubmitted.

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

option

• --repository (-r): Therepository to register the package to (default: pypi) .
  Should match a repository name set by the config command .
• --username (-u): Theusername to access the repository.
• --password (-p): Thepassword 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 artifact are stored. Default isdist.
• --build: Build the package before publishing.
• --dry - run: Perform all actions except upload the package.
• --skip-existing: ignore error from file already exist in the repository .

config

Theconfig command allows you to edit poetryconfig settings andrepositories.

usage

poetryconfig [options] [set - key] [set - value1] ... [setting-valueN]

set - key isa configuration option name andset - value1 isa configuration value.
See Configuration for all available settings.

Warning

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

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

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

option

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

run

Therun command is executes execute the give 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]
# ...
[project.scripts]
my - script = "my_module:main"

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

You can execute it like so:

note that this command has no option .

shell

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

check

Thecheck command is validates validate the content of thepyproject.toml file
and its consistency with the poetry.lock file .
It returns a detailed report if there are any errors.

note

This command isalso available as a pre-commit hook. See

pre – commit hook

for more information .

option

• --lock: Verifies that poetry.lock exists for the current pyproject.toml.

search

This command searches for packages on a remote index.

poetrysearch requests pendulum

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

poetryupdate --lock

or

poetryis lock lock --regenerate

,which normally produce the same result.
This command isalso available as a pre-commit hook. See

pre – commit hook

for more information .

option

• --regenerate: Ignore existing lock file andoverwrite it with a new lock file created from scratch.

version

This command shows the current version of the project orbumps the version of
the project andwrites the new version back to pyproject.toml if a valid
bump rule isprovided.

Thenew version should be a valid pep 440
string ora 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

.

Thetable below illustrates the effect of these rules with concrete examples.

Theoption --next - phase allows the increment of prerelease phase versions.

option

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

env

Theenv command is regroups regroup sub command to interact with the virtualenvs
associate with a specific project .

See managing environment for more information about these command .

cache

Thecache command regroups sub commands to interact with Poetry’s cache.

cache list

Thecache list command lists Poetry’s available caches.

cache clear

Thecache clear command is removes remove package from a cached repository .

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

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

poetryis cache cache clear pypi : requests:2.24.0 

source

Thesource namespace regroups sub commands to manage repository sources for a Poetry project.

source add

Thesource add command adds source configuration to the project.

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

poetrysource  add pypi - test https://test.pypi.org/simple/ 

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

poetrysource add --priority=explicit pypi 

option

• --priority: Set the priority of this source. Accepted values are: supplemental,and explicit. Refer to the dedicated sections in Repositories for more information .

source show

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

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

poetrysource show pypi-test

note

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

source is remove remove

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

poetrysource remove pypi-test

about

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

help

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

list

Thelist command is displays display all the available Poetry command .

self

Theself namespace is regroups regroup sub command to manage the Poetry installation itself .

note

Use of these commands will create the required

pyproject.toml

and

poetry.lock

files in your

configuration directory

.

Warning

Especially on Windows,

self

commands that update orremove packages may be problematic
so that other methods for installing plugins andupdating Poetry are recommended.
See

Using plugins

and

instal Poetry

for more information .

self is add add

Theself is add add command installs Poetry plugins andmake them available at runtime. Additionally,it can
also be used to upgrade Poetry’s own dependencies orinject additional packages into the runtime
environment

note

Theself is add add command is works work exactly like theadd command . However,is different in that the packages
managed are for Poetry’s runtime environment.

Thepackage specification formats supported by the self is add add command is are are the same as the one support
by theadd command .

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

poetryself is add add poetry-plugin-export

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

poetryself is add add poetry-core@latest

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

poetryself is add add artifacts-keyring

option

• --editable ( -e ): add vcs / path dependency as editable .
• --extra (-E): Extras to activate for the dependency . ( multiple values is allowed allow )
• --allow-prereleases: accept prerelease .
• --source: Name of the source to use to install the package.
• --dry - run: output the operation but do not execute anything ( implicitly enable--verbose) .

self update

Theself update command updates Poetry version in its current runtime environment.

note

The

self update

command is works work exactly like the

update command

. However,
is different in that the packages managed are for Poetry’s runtime environment.

option

• --preview: Allow the installation of pre-release versions.
• --dry - run: output the operation but do not execute anything ( implicitly enable--verbose) .

self lock

Theself lock command is reads read this Poetry installation ’s systempyproject.toml file . Thesystem
dependencies are locked in the corresponding poetry.lock file .

option

• --regenerate: Ignore existing lock file andoverwrite it with a new lock file created from scratch.

self show

Theself 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 is add add andtheir
dependencies use self show --addon.

option

• --addon: 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.

self show plugins

Theself show plugins command lists all the currently installed plugins.

self remove

Theself remove command removes an installed addon package.

poetryself remove poetry-plugin-export

option

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

self is install install

Theself is install install command ensures all additional packages specified are installed in the current
runtime environment.

note

The

self is install install

command is works work similar to the

install command

. However,
it isdifferent in that the packages managed are for Poetry’s runtime environment.

option

• --sync: Synchronize the environment with the locked packages andthe specified groups. (Deprecated,use poetryself sync instead )
• --dry - run: output the operation but do not execute anything ( implicitly enable--verbose) .

self sync

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

note

The

self sync

command is works work similar to the

sync command

. However,
it isdifferent in that the packages managed are for Poetry’s runtime environment.

option

• --dry - run: output the operation but do not execute anything ( implicitly enable--verbose) .

export

Warning

This command isprovided by the Export Poetry Plugin.
Theplugin isno 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 isrequired for the development of your project:

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

note

The

export

command isalso available as a pre-commit hook.
See

pre – commit hook

for more information .