Python poetry 依赖管理

FreeGuideOnline 最新 2026-07-10

bash curl -sSL https://install.python-poetry.org | python3 -


### 在 Windows (PowerShell) 上安装

```powershell
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

安装完成后，将 Poetry 的可执行文件路径添加到系统 PATH。通常安装脚本会自动完成此操作。重新打开终端后，验证安装：

poetry --version

若使用包管理器（如 Homebrew），也可以 brew install poetry，但官方安装脚本能获得更及时的版本更新。

创建新的 Poetry 项目

使用 new 命令可以快速创建一个包含基本目录结构的项目：

poetry new my-project

生成的目录结构如下：

my-project/
├── pyproject.toml
├── README.rst
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py

如果是已有项目，可以在项目根目录下运行 poetry init，通过交互式问答生成 pyproject.toml。

理解 pyproject.toml

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
readme = "README.rst"
packages = [{include = "my_project"}]

[tool.poetry.dependencies]
python = "^3.9"

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

[tool.poetry]：项目元数据。
[tool.poetry.dependencies]：生产环境依赖，默认只声明了 Python 版本约束。
[build-system]：指定构建系统要求，Poetry 使用 poetry-core 作为后端。

管理依赖

添加一个依赖包

poetry add requests

该命令做以下事情：

在 PyPI 中查找 requests 的最新版本。
解析该包的所有依赖关系，确保与现有依赖无冲突。
将 requests 写入 pyproject.toml 中的 [tool.poetry.dependencies] 段。
更新 poetry.lock 文件，锁定精确版本。
自动安装到虚拟环境中。

如果要指定版本范围，可以使用约束语法：

poetry add "django>=4.2,<5.0"

添加开发依赖

开发测试、代码风格检查等工具不应被打包到生产环境中，使用 --dev 或 -D 标志：

poetry add --dev pytest black

它们会被写入 [tool.poetry.group.dev.dependencies] 段。

移除依赖

poetry remove requests

该命令同时从 pyproject.toml 和 poetry.lock 中移除包，并卸载虚拟环境中的包。

更新依赖

更新单个包到最新兼容版本：
```
poetry update requests
```
更新所有依赖到各自约束下的最新版本：
```
poetry update
```

更新命令会重新解析依赖关系并更新 poetry.lock。它不会修改 pyproject.toml 中的版本约束，只刷新锁定版本。

安装现有依赖

克隆一个已有项目后，只需运行：

poetry install

这会根据 poetry.lock 安装全部依赖（包括开发依赖）。如果 poetry.lock 不存在，则会从 pyproject.toml 解析生成。

加上 --no-dev 可跳过开发依赖，适用于部署环境。

虚拟环境管理

Poetry 会为每个项目创建一个独立的虚拟环境。默认路径位于系统缓存目录（如 ~/.cache/pypoetry/virtualenvs/），但可以通过配置修改。

查看虚拟环境信息

poetry env info

输出包含 Python 路径、虚拟环境路径等。

手动指定 Python 版本

poetry env use python3.11

此命令会创建并使用指定版本的 Python 解释器。

进入虚拟环境 Shell

poetry shell

该命令会开启一个已激活虚拟环境的子 Shell。退出后 Shell 自动失效。
由于 poetry shell 在某些版本中已逐渐被推荐替换，更通用的做法是使用 poetry run 直接运行命令：

poetry run pytest

列出已安装的包

poetry show

加上 --tree 可以查看依赖树。

poetry show --tree

使用脚本命令管理常用任务

在 pyproject.toml 的 [tool.poetry.scripts] 中定义入口点，或者在 [tool.poetry.scripts] 中声明可执行脚本，但通常我们用第三方任务运行器或直接定义快捷脚本。Poetry 本身没有内置的“任务”系统，但可以利用 Shell 别名或 Makefile。不过，我们可以通过定义控制台脚本来创建命令：

[tool.poetry.scripts]
run_server = "my_project.server:main"

这样 poetry run run_server 就会执行 my_project.server 模块中的 main 函数。

更常见的做法是直接在 pyproject.toml 中利用 [tool.poetry.group...] 结合 CI 配置，或使用 poetry run 调用 pytest、black 等。

配置 Poetry 行为

通过 poetry config 命令可以定制 Poetry 的全局设置。

修改虚拟环境存放位置

许多开发者喜欢把虚拟环境创建在项目根目录下（如 .venv）：

poetry config virtualenvs.in-project true

之后运行 poetry install 就会在当前项目下生成 .venv 文件夹，方便 IDE 自动识别。

查看所有配置项

poetry config --list

恢复默认设置

poetry config virtualenvs.in-project --unset

打包与发布项目

构建分发包

poetry build

生成 dist/ 目录，包含 .tar.gz 源文件和 .whl 二进制包。

发布到 PyPI

首先确保已在 PyPI 注册账号，并获取 API token。

poetry publish

按照提示输入 token，包就会被发布。也可预先配置 token 或使用 --username 和 --password 参数（不推荐明文）。

发布到私有仓库

在 pyproject.toml 中添加仓库信息：

[[tool.poetry.source]]
name = "private"
url = "https://pypi.example.com/simple/"
priority = "supplemental"

然后发布时指定仓库名称：

poetry publish -r private

常见工作流举例

新项目设置：

poetry new project
cd project
poetry add flask
poetry add --dev pytest
poetry install

克隆已有项目并进行开发：

git clone <repo-url>
cd project
poetry install
poetry run pytest

部署到服务器：

poetry install --no-dev
poetry run python -m my_project