Poetry管理Python依赖，Linux虚拟环境教程

本文深入解析了Poetry管理Python依赖与Linux虚拟环境的核心实践，澄清了“默认不激活虚拟环境却自动绑定项目venv”的关键机制，直击import报错的根源——未通过poetry run或poetry shell执行导致环境隔离失效；详解了dependencies与dev-dependencies的本质区别、项目内虚拟环境配置技巧、poetry.lock作为确定性依赖快照不可删除的重要性，以及环境隔离仅作用于进程而非shell的底层逻辑，帮助开发者彻底摆脱手动激活、路径混乱和版本漂移等常见陷阱，实现真正可靠、可复现、跨团队一致的Python项目环境管理。

Poetry 默认不激活虚拟环境，但所有命令（如 poetry run、poetry shell）都自动使用项目绑定的虚拟环境——你不需要手动 source bin/activate，也不该直接用系统 python 执行脚本。

为什么 poetry add 后 import 还报错？

常见现象：执行 poetry add requests 成功，但 Python 脚本里 import requests 仍提示 ModuleNotFoundError。

• 根本原因不是没装包，而是你没通过 Poetry 运行 Python —— 直接敲 python main.py 用的是系统 Python 或当前 shell 激活的其他环境，和 Poetry 无关
• 正确做法是统一用 poetry run python main.py，它会自动注入正确的 PYTHONPATH 和 PATH
• 如果想进交互式环境，用 poetry shell（会启动一个新 shell 并预设好环境变量），退出时输 exit 即可
• 检查当前绑定的环境路径：运行 poetry env info --path，确认输出目录下确实有 site-packages/requests/

pyproject.toml 里 [tool.poetry.dependencies] 和 [tool.poetry.dev-dependencies] 的区别

这两个区块控制的是不同场景下的依赖安装行为，不是“开发用/生产用”这种模糊划分。

• [tool.poetry.dependencies] 中的包，只要执行 poetry install 就一定会被安装（包括 CI 构建、部署等）
• [tool.poetry.dev-dependencies] 中的包，只在你本地开发时生效；除非显式加 --with dev，否则 poetry install --no-dev 不会装它们
• 注意：即使没写 dev-dependencies，pytest 这类工具默认也不会进生产环境 —— 关键看你怎么调用 install，而不是它在哪节里
• 不要把构建工具（如 poetry-core）或打包依赖（如 setuptools）写进这里，它们属于 [build-system] 范畴

Linux 下如何让 Poetry 使用项目内虚拟环境？

默认 Poetry 把虚拟环境建在全局缓存目录（如 ~/.cache/pypoetry/virtualenvs/），这在共享机器或 CI 场景下容易冲突。改用项目内环境更可控。

• 执行：poetry config virtualenvs.in-project true，之后所有 poetry install 都会在项目根目录生成 .venv/
• 这个配置写入 $HOME/.config/pypoetry/config.toml，对所有项目生效；如只想对当前项目生效，加 --local 参数
• 已有项目切换时，先删掉旧环境：poetry env remove python3.11（用 poetry env list 查版本），再运行 poetry install
• Git 提交时记得把 .venv/ 加进 .gitignore —— 它是生成物，不是源码

poetry.lock 文件为什么不能删？

它不是缓存文件，而是 Poetry 解析依赖树后生成的**确定性快照**。删了会导致重装时版本漂移。

• 每次 poetry add 或 poetry update 都会更新它；CI 环境必须基于它还原，否则 poetry install 可能装出不同版本
• 如果你改了 pyproject.toml 里的版本约束（比如把 requests = "^2.28" 改成 "^2.30"），必须运行 poetry lock 或 poetry update 来同步 poetry.lock
• 多人协作时，poetry.lock 必须提交 Git —— 它相当于 npm shrinkwrap 或 pipenv 的 Pipfile.lock
• 误删后不要手动重建，直接 poetry lock --no-update 可从当前 pyproject.toml 重新生成（但会丢失历史解析结果）

最容易被忽略的一点：Poetry 的环境隔离是“进程级”的，不是“shell级”的。你在同一个终端窗口里既可以用 poetry run python，也可以用 poetry shell，但绝不能混用 source .venv/bin/activate 和 Poetry 命令 —— 它们管理的环境元数据不互通，可能导致 poetry env list 看不见你手动激活的环境。

终于介绍完啦！小伙伴们，这篇关于《Poetry管理Python依赖，Linux虚拟环境教程》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！