title: Poetry：Python 项目依赖管理与环境配置指南
date: 2026-11-02
Poetry 安装与配置指南
一、为什么选择 Poetry？
Poetry 是 Python 项目管理工具，主要用于管理项目依赖、虚拟环境、项目构建和发布。
相比单独使用 pip，Poetry 提供了更完整的项目依赖管理机制：
- 依赖解析：自动处理依赖之间的版本约束。
- 版本锁定：通过
poetry.lock锁定依赖版本。 - 环境管理：为不同项目创建独立的 Python 虚拟环境。
- 项目管理：通过
pyproject.toml统一管理项目配置。 - 打包发布：支持构建和发布 Python 软件包。
二、当前运行环境
本机使用 Windows 便携版 Python，不安装第二套 Python。
| 项目 | 配置 |
|---|---|
| Python 版本 | Python 3.10.0 |
| Python 路径 | D:\python\python3.10\python.exe |
| Python 类型 | Windows Embeddable Package |
| Poetry 版本 | 2.1.3 |
| Poetry 安装目录 | D:\python\poetry |
| Poetry 启动文件 | D:\python\poetry\poetry.cmd |
注意：当前 Python 是嵌入式便携版，不包含标准库 venv 模块。因此，不能直接使用 python -m venv 创建虚拟环境。
三、Poetry 安装与启动
1. 准备 Poetry 安装包
从 Poetry 官方发布页面下载对应版本的 wheel 文件：
https://github.com/python-poetry/poetry/releases
例如：
poetry-2.1.3-py3-none-any.whl
2. 安装到指定目录
本机采用指定目录安装方式：
1 | D:\python\python3.10\python.exe -m pip install --target=D:\python\poetry poetry==2.1.3 |
注意：Poetry 与 poetry-core 使用共同的 poetry 顶层包目录。安装或更新时，不要直接使用 --upgrade --force-reinstall 对整个目录进行覆盖，否则可能导致主程序文件丢失。
如果需要更新，应先备份目录，再按照依赖包的安装结构进行处理。
3. 配置 Poetry 启动文件
在 D:\python\poetry 目录下创建 poetry.cmd。
文件内容：
1 | @echo off |
以后通过以下命令启动：
1 | D:\python\poetry\poetry.cmd --version |
预期输出：
1 | Poetry (version 2.1.3) |
将 D:\python\poetry 添加到 Windows PATH，并确保它排在旧的 D:\python\poetry\bin 之前，即可直接使用：
1 | poetry --version |
四、Poetry 基础配置
以下命令均通过 poetry 启动。
1. 设置数据目录
1 | poetry config data-dir "D:\python\poetry\data" |
2. 设置缓存目录
1 | poetry config cache-dir "D:\python\poetry\cache" |
3. 设置虚拟环境目录
希望每个项目都在项目根目录生成 .venv：
1 | poetry config virtualenvs.in-project true |
4. 开启虚拟环境创建
1 | poetry config virtualenvs.create true |
注意：这两个配置只是告诉 Poetry 如何管理虚拟环境，并不代表当前嵌入式 Python 一定能够成功创建虚拟环境。
本机 Python 缺少 venv 模块，需要先进行实际创建测试。
5. 查看配置
1 | poetry config --list |
五、项目管理
1. 初始化已有项目
进入项目目录：
1 | cd /d D:\python\projects\myproject |
执行：
1 | poetry init |
按照提示填写项目名称、版本及依赖信息。
2. 创建新项目
1 | poetry new myproject |
3. 指定项目 Python 解释器
1 | poetry env use "D:\python\python3.10\python.exe" |
注意：该命令指定的是 Python 解释器，不保证嵌入式 Python 一定能够创建虚拟环境。
首次使用时，应检查：
1 | poetry env info |
如果创建失败，应先排查嵌入式 Python 的兼容性，不要反复执行安装命令。
4. 添加依赖
1 | poetry add requests |
5. 删除依赖
1 | poetry remove requests |
6. 安装项目依赖
1 | poetry install |
7. 查看依赖
1 | poetry show |
查看依赖树：
1 | poetry show --tree |
8. 查看虚拟环境信息
1 | poetry env info |
9. 激活虚拟环境
Poetry 2.x 可以执行：
1 | poetry env activate |
该命令会输出当前 Shell 对应的激活命令，需要根据输出在终端执行。
如果使用 Windows CMD，也可以在项目目录执行：
1 | .venv\Scripts\activate.bat |
前提是项目的 .venv 已经成功创建。
六、常用命令速查
| 功能 | 命令 |
|---|---|
| 查看版本 | poetry --version |
| 查看帮助 | poetry --help |
| 初始化项目 | poetry init |
| 创建项目 | poetry new 项目名 |
| 添加依赖 | poetry add 包名 |
| 删除依赖 | poetry remove 包名 |
| 安装依赖 | poetry install |
| 查看依赖 | poetry show |
| 查看依赖树 | poetry show --tree |
| 查看环境 | poetry env info |
| 查看配置 | poetry config --list |
| 更新依赖 | poetry update |
| 构建项目 | poetry build |
七、本机环境特别说明
本机使用的是 Python Embeddable Package，而不是普通 Windows Python 安装版。
因此：
- 不要执行
python -m venv，当前环境没有venv模块。 - 不要随意修改
python310._pth。 - 不要将 Poetry 的依赖直接覆盖安装到同一个目标目录。
- 不要将
PYTHONPATH设置为全局环境变量来解决 Poetry 的启动问题。 - 在正式使用项目之前，先验证 Poetry 是否能够使用当前 Python 创建
.venv。
最终目标：只使用 D 盘现有的 Python 3.10.0，Poetry 独立存放，项目之间通过各自的虚拟环境隔离依赖。
