PyCharm 支持 Poetry 环境但需手动配置：先终端执行 poetry init 和 install，再用 poetry env info -p 获取路径，在 Settings 中选 System Interpreter 指向 bin/python 或 Scripts\python.exe，禁用 IDE 自建虚拟环境，并每次依赖变更后重载项目。
PyCharm 能识别 Poetry 环境，但默认不会自动配置解释器或加载依赖，必须手动绑定 poetry env info -p 输出的路径，并禁用 PyCharm 自带的虚拟环境创建逻辑。
确认 Poetry 已正确安装并初始化项目
PyCharm 不会帮你装 Poetry，也不会自动运行 poetry init 或 poetry install。你得先在终端里完成这些：
- 执行
poetry --version确保命令可用（推荐用curl -sSL https://install.python-poetry.org | python3 -安装） - 在项目根目录运行
poetry init（一路回车可快速生成pyproject.toml） - 运行
poetry install生成虚拟环境并安装依赖（含tool.poetry.dependencies和dev-dependencies） - 用
poetry env info -p查出虚拟环境实际路径（例如/Users/xxx/Library/Caches/pypoetry/virtualenvs/myproject-py3.11）——这个路径后面要用
在 PyCharm 中手动设置 Poetry 解释器
PyCharm 的「Add Python Interpreter」界面不直接支持 Poetry，必须选「System Interpreter」并指向 poetry env info -p 输出的路径下的 bin/python（macOS/Linux）或 Scripts\python.exe（Windows）：
- 打开 File → Settings → Project → Python Interpreter
- 点击右上角齿轮 → Add… → System Interpreter → Location
- 粘贴完整路径，例如：
/Users/xxx/Library/Caches/pypoetry/virtualenvs/myproject-py3.11/bin/python - 确认后 PyCharm 会加载该环境中已安装的包（
poetry show列出的包应全部可见） - ⚠️ 不要勾选 “Make available to all projects” —— Poetry 环境是项目级隔离的
让 PyCharm 正确识别 poetry run 和脚本执行行为
PyCharm 默认用自己选中的解释器直接运行脚本，但 Poetry 项目中有些命令（如 poetry run pytest、poetry run myscript.py）需要走 poetry run 才能加载正确的环境变量和脚本入口点：
立即学习“Python免费学习笔记（深入）”；
- 运行配置（Run Configuration）中，把 Python interpreter 设为刚才配好的 Poetry 解释器
- 若需等效于
poetry run xxx，在 Script path 填poetry，参数填run xxx（比如run pytest tests/） - 对于
pyproject.toml中定义的[tool.poetry.scripts]，PyCharm 不会自动注册为可运行目标，得手动建 External Tool 或用 Terminal 运行poetry run mycmd - 调试时，PyCharm 的 debugger 会继承 Poetry 环境，但
sys.path可能漏掉src/目录 —— 需在Settings → Project → Project Structure中将src标记为 Sources
避免 Poetry 与 PyCharm 缓存冲突的实操要点
PyCharm 会缓存包信息、类型提示和语法检查结果，而 Poetry 可能在终端里更新了依赖但 PyCharm 没感知到：
- 每次运行
poetry add、poetry remove或poetry update后，手动触发 File → Reload project from Disk（或点击右下角 “Reload project” 提示） - 如果出现 “unresolved reference” 却确定包已安装，检查
poetry env info -p路径是否仍有效（Poetry 有时会清理旧环境），必要时删掉poetry env remove python_version再重装 - 关闭 PyCharm 的 Settings → Project → Python Interpreter → Show all files 里的 “Always use this interpreter for new projects”，防止它偷偷覆盖 Poetry 项目配置
- 不建议开启 PyCharm 的 “Suggest to create virtual environment when no interpreter is selected” —— Poetry 项目不该由 IDE 创建 venv
最易被忽略的是：PyCharm 的代码补全和类型推导依赖 py.typed 或 stub 包，而 Poetry 安装的某些包（尤其纯 C 扩展或未打标的包）可能不提供，这时即使解释器配对了，也会误报“unresolved”。遇到这种情况，别急着换工具，先查 poetry show --tree package_name 确认是否真装上了，再看 PyCharm 是否把 .venv 或 Poetry 缓存路径加进了 External Libraries 的索引范围。
