一、为什么要接入 Poetry
很多 Python 工程一开始通过 requirements.txt 管理依赖。随着接口、报表、脚本命令、导出工具逐渐增多，继续手动维护 requirements.txt 会越来越散。
Poetry 的好处是把项目配置、Python 版本约束、依赖列表和锁定文件统一收口到 pyproject.toml 和 poetry.lock。这样启动、安装和迁移环境都会更清晰。
二、Poetry 管理的内容
Poetry 管理的不只是依赖，还包括完整项目信息：
项目元数据
Python 版本限制
依赖声明
锁定后的精确版本
统一的运行命令入口
也就是说，requirements.txt 更像是一份安装清单，而 pyproject.toml 更像是一份完整配置文件。
三、常见 pyproject.toml 结构
一个常见的 Poetry 配置可以写成这样：
[project]
name = "demo-app"
version = "0.1.0"
description = "Python demo application"
readme = "README.md"
requires-python = ">=3.11,<4.0"
dependencies = [
"pandas==2.2.2",
"matplotlib==3.9.2",
"openpyxl==3.1.5",
"fastapi>=0.115.0,<1.0.0",
"uvicorn[standard]>=0.30.0,<1.0.0",
]
[tool.poetry]
package-mode = false
如果当前更偏向脚本工程、练习工程或者内部工具，而不是需要发布到 PyPI 的库，那么 package-mode = false 会更合适。
四、poetry.lock 有什么用
poetry.lock 用来锁定最终解析出来的依赖版本。
比如声明了 fastapi 和 uvicorn，Poetry 在解析时还会带出 starlette、pydantic 以及其它间接依赖。poetry.lock 会把这些版本固定下来。
这样做的价值是：
不同机器安装出来的环境更一致
今天能跑的工程，明天重装环境时更容易复现
出问题时更容易定位是代码问题还是依赖漂移问题
五、接入 Poetry 后怎么用
常用命令如下：
poetry install
poetry run python -m your_module
poetry run python your_script.py
poetry run uvicorn api:app --reload --port 8010
这样之后，不需要再手动激活不同虚拟环境，也不需要混用 pip install 和本地 Python。命令入口会统一很多。
六、为什么接口依赖也要放进 Poetry
如果一个工程里已经有接口层，就不应该只把数据分析类依赖写进配置，而把 FastAPI、uvicorn 之类的运行依赖放在外面单独装。
更稳妥的方式是把运行时真正需要的依赖全部写进 pyproject.toml。这样后面别人接手时，执行 poetry install 就能得到完整环境。
七、README 也要一起更新
接入 Poetry 之后，README 里的命令最好一起切换。
例如原来常见的是：
python -m venv .venv
pip install -r requirements.txt
切换之后更适合写成：
poetry install
poetry run python -m your_module
poetry run uvicorn api:app --reload
这样文档和配置保持一致，后面照着 README 跑也不会走偏。
八、端口与启动命令
启动 FastAPI 时，如果直接使用 8000 端口，有时会遇到端口占用或者系统策略拦截。
因此实际使用时，可以直接指定一个可用端口：
poetry run uvicorn api:app --reload --port 8010
九、接入 Poetry 带来的变化
依赖不再分散在命令和
requirements.txt中Python 版本约束写进了项目配置
接口、报表、导出相关依赖可以统一纳管
工程可以通过
poetry run统一启动后续继续扩展脚本、接口和工具时更容易维护
Tips
如果是脚本型工程，可以优先考虑：
[tool.poetry]
package-mode = false
如果工程里已经开始出现 API、报表、数据初始化脚本并存的情况，Poetry 往往会比单独维护 requirements.txt 更省心。
如果后续要继续扩展测试、格式化或类型检查工具，也建议继续放进 pyproject.toml 统一管理。
评论区