命令

命令 #

您已经了解了如何使用命令行界面来完成一些操作。本章将记录所有可用的命令。

要从命令行获取帮助，只需调用 poetry 来查看完整的命令列表，然后将 --help 与任何命令结合使用即可获得更多信息。

全局选项 #

--verbose (-v|vv|vvv): 提高消息的详细程度：“-v” 用于正常输出，“-vv” 用于更详细的输出，“-vvv” 用于调试。
--help (-h) : 显示帮助信息。
--quiet (-q) : 不输出任何消息。
--ansi: 强制使用 ANSI 输出。
--no-ansi: 禁用 ANSI 输出。
--version (-V): 显示此应用程序版本。
--no-interaction (-n): 不要询问任何交互式问题。
--no-plugins: 禁用插件。
--no-cache: 禁用 Poetry 源缓存。
--directory=DIRECTORY (-C): Poetry 命令的工作目录（默认为当前工作目录）。

new #

此命令将帮助您通过创建适合大多数项目的目录结构来启动您的新 Python 项目。

poetry new my-package

将创建一个如下所示的文件夹

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

如果您想将项目命名为与文件夹不同的名称，可以传递 --name 选项

poetry new my-folder --name my-package

如果您想使用 src 文件夹，可以使用 --src 选项

poetry new --src my-package

这将创建一个如下所示的文件夹结构

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

--name 选项足够智能，可以检测命名空间包并为您创建所需的结构。

poetry new --src --name my.package my-package

将创建以下结构

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

选项 #

--name: 设置生成的包名称。
--src: 为项目使用 src 布局。
--readme: 指定自述文件扩展名。默认值为 md。如果您打算发布到 PyPI，请牢记 PyPI 友好自述文件的建议。

init #

此命令将通过提示您提供有关包的基本信息来帮助您以交互方式创建 pyproject.toml 文件。

它将以交互方式要求您填写字段，同时使用一些智能默认值。

poetry init

选项 #

--name: 包的名称。
--description: 包的描述。
--author: 包的作者。
--python 兼容的 Python 版本。
--dependency: 要使用版本约束要求的包。应采用 foo:1.0.0 格式。
--dev-dependency: 开发需求，请参见 --dependency。

install #

install 命令从当前项目读取 pyproject.toml 文件，解析依赖项并安装它们。

poetry install

如果当前目录中存在 poetry.lock 文件，它将使用其中的确切版本，而不是解析它们。这确保了所有使用该库的人员都将获得相同版本的依赖项。

如果不存在 poetry.lock 文件，Poetry 将在依赖项解析后创建一个。

如果您想在安装过程中排除一个或多个依赖项组，可以使用 --without 选项。

poetry install --without test,docs

注意

--no-dev 选项现已弃用。您应该改用 --only main 或 --without dev 表示法。

您还可以使用 --with 选项选择可选的依赖项组。

poetry install --with test,docs

还可以通过使用 only 选项仅安装特定的依赖项组。

poetry install --only test,docs

要仅安装项目本身而不安装任何依赖项，请使用 --only-root 标志。

poetry install --only-root

有关依赖项组的更多信息，请参见依赖项组。

如果您想同步您的环境 - 并确保它与锁定文件匹配 - 请使用 --sync 选项。

poetry install --sync

--sync 可以与组相关选项结合使用

poetry install --without dev --sync
poetry install --with docs --sync
poetry install --only dev --sync

您还可以通过传递 -E|--extras 选项来指定要安装的额外内容（有关更多信息，请参见额外内容）。传递 --all-extras 以安装为项目定义的所有额外内容。

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

额外内容对 --sync 不敏感。任何未指定的额外内容都将始终被删除。

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

默认情况下，poetry 将在每次运行 install 时安装项目的包

$ poetry install
Installing dependencies from lock file

No dependencies to install or update

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

如果您想跳过此安装，请使用 --no-root 选项。

poetry install --no-root

类似于 --no-root，您可以使用 --no-directory 跳过目录路径依赖项

poetry install --no-directory

这主要在 CI 中缓存或构建 Docker 映像时有用。有关此选项的更多信息，请参见常见问题解答条目。

默认情况下，poetry 在安装过程中不会将 Python 源文件编译为字节码。这加快了安装过程，但第一次执行可能需要更多时间，因为 Python 随后会自动将源文件编译为字节码。如果您想在安装过程中将源文件编译为字节码，可以使用 --compile 选项

poetry install --compile

注意

如果 installer.modern-installation 设置为 false，则 --compile 选项无效，因为旧的安装程序始终将源文件编译为字节码。

选项 #

--without: 要忽略的依赖项组。
--with: 要包含的可选依赖项组。
--only: 要包含的唯一依赖项组。
--only-root: 仅安装根项目，排除所有依赖项。
--sync: 将环境与锁定包和指定的组同步。
--no-root: 不要安装根包（您的项目）。
--no-directory: 跳过所有目录路径依赖项（包括传递依赖项）。
--dry-run: 输出操作，但不执行任何操作（隐式启用 –verbose）。
--extras (-E): 要安装的功能（允许使用多个值）。
--all-extras: 安装所有额外功能（与 –extras 冲突）。
--compile: 将 Python 源文件编译为字节码。
--no-dev: 不要安装开发依赖项。（**已弃用**，请改用 --only main 或 --without dev）
--remove-untracked: 删除锁定文件中未出现的依赖项。（**已弃用**，请改用 --sync）

注意

当指定 --only 时，--with 和 --without 选项将被忽略。

更新 #

为了获取依赖项的最新版本并更新 poetry.lock 文件，您应该使用 update 命令。

poetry update

这将解析项目的全部依赖项，并将确切的版本写入 poetry.lock。

如果您只想更新几个包，而不是全部，可以像这样列出它们

poetry update requests toml

请注意，这不会更新 pyproject.toml 文件中指定的依赖项的版本约束之外的版本。换句话说，如果为 foo 指定的版本约束为 ~2.3 或 2.3，并且 2.4 可用，则 poetry update foo 将不会执行任何操作。为了更新 foo，您必须更新约束，例如 ^2.3。您可以使用 add 命令执行此操作。

选项 #

--without: 要忽略的依赖项组。
--with: 要包含的可选依赖项组。
--only: 要包含的唯一依赖项组。
--dry-run : 输出操作，但不执行任何操作（隐式启用 –verbose）。
--no-dev : 不要更新开发依赖项。（**已弃用**，请改用 --only main 或 --without dev）
--lock : 不执行安装（只更新锁定文件）。
--sync: 将环境与锁定包和指定的组同步。

注意

当指定 --only 时，--with 和 --without 选项将被忽略。

添加 #

add 命令将所需的包添加到您的 pyproject.toml 中并安装它们。

如果您没有指定版本约束，poetry 将根据可用的包版本选择一个合适的版本。

poetry add requests pendulum

注意

默认情况下，包只从默认包源中查找。您可以修改默认源（PyPI）；或添加和使用补充包源或显式包源。

有关更多信息，请参阅包源文档。

您也可以在添加包时指定约束

# 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

注意

有关 @ 运算符的更多信息，请参阅依赖项规范页面。

如果您尝试添加一个已经存在的包，您将收到错误。但是，如果您指定了约束，如上所示，则将使用指定的约束更新依赖项。

如果您想获取已经存在的依赖项的最新版本，可以使用特殊的 latest 约束

poetry add pendulum@latest

注意

有关为包设置版本约束的更多信息，请参阅依赖项规范。

您也可以添加 git 依赖项

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

或使用 ssh 代替 https

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

# or alternatively:
poetry add git+ssh://git@github.com:sdispater/pendulum.git

如果您需要检出特定的分支、标签或修订版，您可以在使用 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

或引用子目录

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

您也可以添加本地目录或文件

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

如果您希望以可编辑模式安装依赖项，可以使用 --editable 选项。

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

或者，您可以在 pyproject.toml 文件中指定它。这意味着本地目录中的更改将直接反映在环境中。

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

注意

在 poetry 1.1 之前，路径依赖项默认情况下以可编辑模式安装。您应该始终显式设置 develop 属性，以确保所有 poetry 版本的行为一致。

注意

develop 属性是 Poetry 特有的功能，因此它不包含在包分发元数据中。换句话说，它只在使用 Poetry 安装项目时才会被考虑。

如果您要安装的包提供额外功能，您可以在添加包时指定它们

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

警告

某些 shell 可能将方括号（[ 和 ]）视为特殊字符。建议始终引用包含这些字符的参数，以防止意外的 shell 扩展。

如果您想将包添加到特定组的依赖项中，可以使用 --group (-G) 选项

poetry add mkdocs --group docs

有关依赖项组的更多信息，请参见依赖项组。

选项 #

--group (-G): 要将依赖项添加到其中的组。
--dev (-D): 将包添加为开发依赖项。（**已弃用**，请改用 -G dev）
--editable (-e): 将 vcs/path 依赖项添加为可编辑的。
--extras (-E): 要为依赖项激活的额外功能。（允许使用多个值）
--optional: 添加为可选依赖项。
--python: 必须安装依赖项的 Python 版本。
--platform: 必须安装依赖项的平台。
--source: 用于安装包的源的名称。
--allow-prereleases: 接受预发布版本。
--dry-run: 输出操作，但不执行任何操作（隐式启用 –verbose）。
--lock : 不执行安装（只更新锁定文件）。

删除 #

remove 命令从当前已安装的包列表中删除一个包。

poetry remove pendulum

如果您想从特定组的依赖项中删除一个包，可以使用 --group (-G) 选项

poetry remove mkdocs --group docs

有关依赖项组的更多信息，请参见依赖项组。

选项 #

--group (-G): 要从中删除依赖项的组。
--dev (-D): 从开发依赖项中删除一个包。（**已弃用**，请改用 -G dev）
--dry-run : 输出操作，但不执行任何操作（隐式启用 –verbose）。
--lock : 不执行操作（只更新锁定文件）。

显示 #

要列出所有可用的包，可以使用 show 命令。

poetry show

如果您想查看特定包的详细信息，可以传递包名。

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

选项 #

--without: 要忽略的依赖项组。
--why: 在显示完整列表或单个包的 --tree 时，显示它们是直接依赖项还是由其他包要求。
--with: 要包含的可选依赖项组。
--only: 要包含的唯一依赖项组。
--no-dev: 不要列出开发依赖项。（**已弃用**，请改用 --only main 或 --without dev）
--tree: 将依赖项列为树状结构。
--latest (-l): 显示最新版本。
--outdated (-o): 显示最新版本，但只显示过时的包。
--all (-a): 显示所有包（即使是不兼容当前系统的包）。
--top-level (-T): 只显示显式定义的包。

注意

当指定 --only 时，--with 和 --without 选项将被忽略。

构建 #

build 命令构建源代码和轮子存档。

poetry build

请注意，目前只支持纯 Python 轮子。

选项 #

--format (-f): 将格式限制为 wheel 或 sdist。
--output (-o): 设置构建工件的输出目录。默认值为 dist。

发布 #

此命令将使用 build 命令之前构建的包发布到远程存储库。

如果这是第一次提交，它将自动注册包，然后再上传。

poetry publish

如果您传递 --build 选项，它也可以构建包。

注意

有关如何配置和使用可发布存储库的更多信息，请参阅可发布存储库。

选项 #

--repository (-r): 要将包注册到的存储库（默认值：pypi）。应与 config 命令设置的存储库名称匹配。
--username (-u): 访问存储库的用户名。
--password (-p): 访问存储库的密码。
--cert: 访问存储库的证书颁发机构。
--client-cert: 访问存储库的客户端证书。
--dist-dir: 存储构建工件的 dist 目录。默认值为 dist。
--build: 在发布之前构建包。
--dry-run: 执行所有操作，除了上传包。
--skip-existing: 忽略存储库中已存在的文件的错误。

注意

有关如何配置凭据的更多信息，请参阅配置凭据。

配置 #

config 命令允许您编辑 poetry 配置设置和存储库。

poetry config --list

用法 #

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

setting-key 是配置选项名称，setting-value1 是配置值。有关所有可用设置，请参阅配置。

警告

如果您的值可能以连字符 (-) 开头，请使用 -- 终止选项解析，例如

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

如果没有 --，如果 ${GITLAB_JOB_TOKEN} 以连字符开头，此命令将失败。

选项 #

--unset: 删除名为 setting-key 的配置元素。
--list: 显示当前配置变量列表。
--local: 设置/获取特定于项目的设置（在本地配置文件 poetry.toml 中）。

运行 #

run 命令在项目的虚拟环境中执行给定的命令。

poetry run python -V

它还可以执行 pyproject.toml 中定义的脚本之一。

因此，如果您定义了一个这样的脚本

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

您可以像这样执行它

poetry run my-script

请注意，此命令没有选项。

shell #

shell 命令在项目的虚拟环境中生成一个 shell。

默认情况下，会检测并使用当前活动的 shell。如果失败，则使用通过环境变量 SHELL（在 *nix 上）或 COMSPEC（在 Windows 上）定义的 shell。

如果虚拟环境不存在，则会创建它。

poetry shell

请注意，此命令启动一个新的 shell 并激活虚拟环境。

因此，应使用 exit 正确退出 shell 和虚拟环境，而不是 deactivate。

注意

Poetry 在内部使用 Shellingham 项目来检测当前活动的 shell。

检查 #

check 命令验证 pyproject.toml 文件的内容及其与 poetry.lock 文件的一致性。如果存在任何错误，它将返回详细的报告。

注意

此命令也可以用作 pre-commit 钩子。有关更多信息，请参阅 pre-commit 钩子。

poetry check

选项 #

--lock：验证当前 pyproject.toml 是否存在 poetry.lock。

搜索 #

此命令在远程索引中搜索包。

poetry search requests pendulum

锁定 #

此命令锁定（不安装）pyproject.toml 中指定的依赖项。

注意

默认情况下，这将锁定所有依赖项到最新的可用兼容版本。要仅刷新锁定文件，请使用 --no-update 选项。此命令也可以用作 pre-commit 钩子。有关更多信息，请参阅 pre-commit 钩子。

poetry lock

选项 #

--check：验证 poetry.lock 是否与 pyproject.toml 一致。（已弃用）请改用 poetry check --lock。
--no-update：不要更新锁定的版本，只刷新锁定文件。

版本 #

此命令显示项目的当前版本，或者如果提供了有效的提升规则，则提升项目的版本并将新版本写回 pyproject.toml。

新版本应为有效的 PEP 440 字符串或有效的提升规则：patch、minor、major、prepatch、preminor、premajor、prerelease。

注意

如果您想对项目使用语义版本控制，请参阅此处。

下表说明了这些规则在具体示例中的效果。

规则	之前	之后
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

--next-phase 选项允许递增预发布阶段版本。

规则	之前	之后
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

选项 #

--next-phase：递增当前版本的阶段。
--short (-s)：仅输出版本号。
--dry-run：不更新 pyproject.toml 文件。

导出 #

此命令将锁定文件导出到其他格式。

poetry export -f requirements.txt --output requirements.txt

警告

此命令由 Export Poetry Plugin 提供。在未来的 Poetry 版本中，此插件将不再默认安装。为了避免出现重大更改并使您的自动化向前兼容，请显式安装 poetry-plugin-export。有关如何安装插件的详细信息，请参阅使用插件。

注意

此命令也可以用作 pre-commit 钩子。有关更多信息，请参阅 pre-commit 钩子。

注意

与 install 命令不同，此命令仅包含在 tool.poetry.dependencies 中定义的隐式 main 组中的项目依赖项，在不指定任何选项的情况下使用时。

选项 #

--format (-f)：要导出的格式（默认：requirements.txt）。目前，仅支持 constraints.txt 和 requirements.txt。
--output (-o)：输出文件的名称。如果省略，则打印到标准输出。
--dev：包含开发依赖项。（已弃用，请改用 --with dev）
--extras (-E)：要包含的额外依赖项集。
--without: 要忽略的依赖项组。
--with: 要包含的可选依赖项组。
--only: 要包含的唯一依赖项组。
--without-hashes：从导出的文件中排除哈希值。
--without-urls：从导出的文件中排除源代码库 URL。
--with-credentials：包含额外索引的凭据。

env #

env 命令将子命令组合在一起，以与特定项目关联的虚拟环境进行交互。

有关这些命令的更多信息，请参阅管理环境。

缓存 #

cache 命令将子命令组合在一起，以与 Poetry 的缓存进行交互。

cache list #

cache list 命令列出 Poetry 可用的缓存。

poetry cache list

cache clear #

cache clear 命令从缓存的存储库中删除包。

例如，要清除 pypi 存储库中所有包的缓存，请运行

poetry cache clear pypi --all

要仅从缓存中删除特定包，您必须以 cache:package:version 的形式指定缓存条目

poetry cache clear pypi:requests:2.24.0

源 #

source 命名空间将子命令组合在一起，以管理 Poetry 项目的存储库源。

source add #

source add 命令将源配置添加到项目中。

例如，要添加 pypi-test 源，您可以运行

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

您不能对自定义存储库使用 pypi 名称，因为它保留供默认 PyPI 源使用。但是，您可以设置 PyPI 的优先级

poetry source add --priority=explicit pypi

选项 #

--default：将此源设置为默认（禁用 PyPI）。已弃用，请改用 --priority。
--secondary：将此源设置为辅助源。已弃用，请改用 --priority。
--priority：设置此源的优先级。接受的值为：default、secondary、supplemental 和 explicit。有关更多信息，请参阅存储库中的专用部分。

注意

最多只能提供上述选项之一。有关更多信息，请参阅包源。

source show #

source show 命令显示项目所有配置源的信息。

poetry source show

或者，您可以通过指定其名称来显示一个或多个源的信息。

poetry source show pypi-test

注意

此命令仅显示通过 pyproject.toml 配置的源，不包括隐式默认 PyPI。

source remove #

source remove 命令从您的 pyproject.toml 中删除配置的源。

poetry source remove pypi-test

关于 #

about 命令显示有关 Poetry 的全局信息，包括当前版本和 poetry-core 的版本。

poetry about

帮助 #

help 命令显示全局帮助或特定命令的帮助。

要显示全局帮助

poetry help

要显示特定命令的帮助，例如 show

poetry help show

注意

--help 选项也可以传递给任何命令以获取特定命令的帮助。

例如

poetry show --help

列表 #

list 命令显示所有可用的 Poetry 命令。

poetry list

自身 #

self 命名空间将子命令组合在一起，以管理 Poetry 本身的安装。

注意

使用这些命令将在您的配置目录中创建所需的 pyproject.toml 和 poetry.lock 文件。

警告

特别是在 Windows 上，更新或删除包的 self 命令可能存在问题，因此建议使用其他方法来安装插件和更新 Poetry。有关更多信息，请参阅使用插件和安装 Poetry。

self add #

self add 命令安装 Poetry 插件并在运行时使其可用。此外，它还可以用于升级 Poetry 自己的依赖项或将其他包注入运行时环境

注意

self add 命令的工作原理与 add 命令完全相同。但是，不同之处在于管理的包是针对 Poetry 的运行时环境的。

self add 命令支持的包规范格式与 add 命令支持的格式相同。

例如，要安装 poetry-plugin-export 插件，您可以运行

poetry self add poetry-plugin-export

要更新到最新的 poetry-core 版本，您可以运行

poetry self add poetry-core@latest

要添加密钥环提供程序 artifacts-keyring，您可以运行

poetry self add artifacts-keyring

选项 #

--editable (-e): 将 vcs/path 依赖项添加为可编辑的。
--extras (-E): 要为依赖项激活的额外功能。（允许使用多个值）
--allow-prereleases: 接受预发布版本。
--source: 用于安装包的源的名称。
--dry-run: 输出操作，但不执行任何操作（隐式启用 –verbose）。

self update #

self update 命令更新 Poetry 在其当前运行时环境中的版本。

注意

self update 命令的工作原理与 update 命令完全相同。但是，它与 update 命令的不同之处在于，它管理的是 Poetry 运行时环境的包。

poetry self update

选项 #

--preview：允许安装预发布版本。
--dry-run: 输出操作，但不执行任何操作（隐式启用 –verbose）。

self lock #

self lock 命令读取此 Poetry 安装的系统 pyproject.toml 文件。系统依赖项将锁定在相应的 poetry.lock 文件中。

poetry self lock

选项 #

--check：验证 poetry.lock 是否与 pyproject.toml 一致。（已弃用）
--no-update：不要更新锁定的版本，只刷新锁定文件。

self show #

self show 命令的行为类似于 show 命令，但在 Poetry 的运行时环境中工作。它列出了 Poetry 安装环境中安装的所有包。

要仅显示通过 self add 添加的附加包及其依赖项，请使用 self show --addons。

poetry self show

选项 #

--addons：仅列出已安装的附加组件包。
--tree: 将依赖项列为树状结构。
--latest (-l): 显示最新版本。
--outdated (-o): 显示最新版本，但只显示过时的包。

self show plugins #

self show plugins 命令列出所有当前安装的插件。

poetry self show plugins

self remove #

self remove 命令删除已安装的附加组件包。

poetry self remove poetry-plugin-export

选项 #

--dry-run：输出操作，但不会执行任何操作（隐式启用 –verbose）。

self install #

self install 命令确保当前运行时环境中安装了所有指定的附加包。

注意

self install 命令的工作原理类似于 install 命令。但是，它与 install 命令的不同之处在于，它管理的是 Poetry 运行时环境的包。

poetry self install --sync

选项 #

--sync: 将环境与锁定包和指定的组同步。
--dry-run: 输出操作，但不执行任何操作（隐式启用 –verbose）。