EPGF 新手教程 12在 PyCharm（中文版 GUI）中创建 Poetry 项目环境，并把 Poetry 做成“项目自包含”（工具本地化为必做环节）

【EPGF 白皮书】路径治理驱动的多版本 Python 架构------ Windows 环境治理与 AI 教学开发体系

EPGF 新手教程 12

在 PyCharm（中文版 GUI）中创建 Poetry 项目环境，并把 Poetry 做成"项目自包含"（工具本地化为必做环节）

副标题：Poetry 是依赖与环境管理的现代方案，但在 EPGF 中，父级治理 + 项目本地化缺一不可

开篇结论（先给读者一句定心丸）

Poetry 可以在 PyCharm 中作为环境类型被配置，IDE 甚至能自动创建 pyproject.toml 并帮助你管理依赖；但是 Poetry 的默认行为并不保证工具可执行文件被放入项目的 .venv\Scripts 中 ，从期的环境管理来看，这是不利于项目的独立管理的，因此在 EPGF 架构下，完成环境创建后务必在项目 .venv 内再次本地化 Poetry（pip install poetry 或启用 virtualenvs.in-project = true 并让 Poetry 在项目内部创建虚拟环境），否则锁文件虽然存在，执行这些锁文件的"工具"却可能不存在，导致迁移与复现失败。(JetBrains)

一、前置（你在 01--11 已经完成的治理回顾）

EPGF 新手教程 00一次搭好、终身不乱：Windows Python 环境治理（EPGF）系列总览 / 阅读路线图
 EPGF 新手教程 01为什么 EPGF 能在一台 Windows 上，搞定所有虚拟环境？------一次搭好，终身不乱的 Python 环境治理逻辑（新手也能看懂）
EPGF 新手教程 02第一次安装就不踩坑：Anaconda 正确安装与路径一次性治理------把 Python 安装在 D:\A，从此不再折腾环境变量
 EPGF 新手教程 03不用重装、不用记命令在一台 Windows 上创建多个 Python 版本（全图形界面）
EPGF 新手教程 04一个项目一个环境：PyCharm 是如何帮你"自动隔离"的？（全 GUI，新手零命令）
EPGF 新手教程 05项目已经隔离了，为什么环境还是会乱？------被 90% 新手忽略的"工具污染"，才是真正的隐形杀手
 EPGF 新手教程 06一次安装，全局可用：为什么工具要"住进 Python 版本里"？
EPGF 新手教程 07所有"虚拟环境工具"到底是什么？------一次看懂 venv / virtualenv / conda / uv / poetry / hatch（不再混乱）
EPGF 新手教程 08一次装齐所有工具链，为什么必须跟着 Python 版本走？------工具本地化，才是 Windows 上永不混乱的终极解法（新手必读）
EPGF 新手教程 09｜工具本地化：为什么项目必须自带工具链？------只有 .venv 真正"自给自足"，环境才能迁移、复现、长期不乱（新手必读）
EPGF 新手教程 10｜virtualenv：PyCharm 是如何创建第一个"真正自包含"的项目环境的？
EPGF 新手教程 11在 PyCharm（中文版 GUI）中创建 uv 环境，并把 uv 做到"项目自包含"（工具本地化为必做环节）

在前面的章节你已完成：

将 Anaconda 安装在 D:\A，并建立版本层，例如 D:\A\envs\py311；
在父级 Python（版本层）统一安装过常用工具（包括 Poetry），父级路径示例为：
复制代码
```
D:\A\envs\py311\python.exe
D:\A\envs\py311\Scripts\poetry.exe
```

这些是 EPGF 的"统一来源层" ，用于集中治理与版本管理，但并不是项目可迁移性的最终保障。(JetBrains)

二、PyCharm 对 Poetry 的支持要点（官方/要点）

PyCharm 可以在"创建项目"或"添加解释器"时选择 Poetry 作为环境类型 ，并会为项目创建或识别 pyproject.toml。(JetBrains)
如果 PyCharm 没能自动检测到 Poetry，你可以：
- 让 PyCharm 通过 pip 自动安装 Poetry（"Install poetry via pip"），或
- 指定现有的 poetry.exe 路径（即父级工具位置）。(JetBrains)

（上述是官方支持说明的简要摘录，读者可点击官方文档核验。(JetBrains)）

三、EPGF 下的 GUI 流程（逐步、中文界面）

设计原则（快速提示）

父级统一安装（用于治理与版本来源）

PyCharm 指定父级 python.exe + 父级 poetry.exe（若需要）以创建项目环境

工具本地化： 在项目 .venv 内再次安装 Poetry（或按 Poetry 配置由其在项目内创建 env）以保证工具随项目自包含

步骤 1 --- 新建项目

PyCharm → 文件 → 新建项目（Create New Project）。

步骤 2 --- 选择 "Poetry" 作为环境类型

在右侧环境配置区域：

环境类型 ：选择 Poetry（不是 venv/Conda/System）。
Python 解释器来源 ：选择 已有解释器，并指向父级解释器，例如：
复制代码
```
D:\A\envs\py311\python.exe
```

说明：Poetry 必须知道基于哪个 Python 来构建环境；这一步明确了"父级来源"。(JetBrains)

步骤 3 --- 如果 PyCharm 未自动检测 Poetry：指定或安装

PyCharm 在检测不到 Poetry 时，会给出选项：

点击 Install poetry via pip （让 PyCharm 在所选解释器下为你安装 Poetry）

或者
手动指定 poetry.exe 的路径（父级 Poetry）：
复制代码
```
D:\A\envs\py311\Scripts\poetry.exe
```

二选一（通常在 EPGF 流程中我们偏好：父级先统一安装 → 指定父级路径，保证治理一致；若临时无父级可用，可让 PyCharm 临时安装）。(JetBrains)

步骤 4 --- 确认"在项目内创建虚拟环境"的选项（可选，但推荐）

Poetry 默认把虚拟环境放在 Poetry 缓存（如 ~/.cache/pypoetry/virtualenvs），如果你希望环境在项目目录内（便于 .venv 自包含），可在 Poetry 配置中设置：

复制代码

poetry config virtualenvs.in-project true

或在 PyCharm 创建界面勾选"Create an in-project environment"（如果可用），这样 Poetry 会在项目目录创建 .venv（或 .venv 等命名），更利于 EPGF 的迁移思路。(诗歌)

步骤 5 --- 点击【创建】完成

PyCharm 会创建项目、生成或更新 pyproject.toml，并为你关联解释器。项目初始状态可能已包含 pyproject.toml（如果使用 Poetry 类型创建）。(JetBrains)

【笔记】PyCharm 中创建Poetry解释器
 【PyCharm必会基础】正确移除解释器及虚拟环境（以 Poetry 为例）
【笔记】结合 Conda任意创建和配置不同 Python 版本的双轨隔离的 Poetry 虚拟环境
 【笔记】Poetry虚拟环境创建示例
 教程：PyCharm 中搭建多级隔离的 Poetry 环境（从 Anaconda 到项目专属.venv）
Anaconda 全环境工具链路径树管理和环境创建指南（Poetry、Pipenv、venv、uv、Hatch）
使用命令行创建项目本地的 Poetry 虚拟环境实战演示 ------ 基于《Python 多版本与开发环境治理架构设计》的最佳实践
 使用 Conda 工具链创建 Poetry 本地虚拟环境全记录------基于《Python 多版本与开发环境治理架构设计》
【笔记】PyCharm 2025.2 EAP 创建 Poetry 和 Hatch 环境的踩坑实录与反馈
 【终极实战】Conda/Poetry/Virtualenv/Pipenv/Hatch 多工具协同 + Anaconda×PyCharm：构建 Python 全版本栈隔离体系与虚拟环境自动化管理指南

四、创建后的"状态检查"与"半成品"判定

创建完成后，检查项目目录下 .venv\Scripts（或 Poetry 在项目内创建的虚拟环境目录）：

可能包含：
复制代码
```
python.exe
pip.exe
```
但是 不一定包含 poetry.exe（Poetry 的可执行文件）------取决于你是否在项目环境内本地化安装了 Poetry 或是否配置 Poetry 在项目内创建 env。

这正是 EPGF 的关注点：仅靠父级的 poetry.exe 并不能保证项目自包含 。(诗歌)

五、EPGF 的关键动作（必做）：工具本地化（把 poetry.exe 放进项目环境）

为什么要做？

Poetry 生成了 pyproject.toml 与 poetry.lock（版本确定性），但这些锁文件需要由 Poetry 来解释与执行。若项目迁移后 .venv 里没有 poetry.exe，激活环境后你将无法直接运行 poetry install 来恢复或管理依赖，环境虽然有锁文件但"无执行器"（工具缺失），这会破坏迁移复现能力。详见下节理论高潮引用。(诗歌)

在 PyCharm 终端中执行（GUI 下的必要命令）

打开 PyCharm 下方 终端（Terminal） （PyCharm 会自动激活项目的 .venv）。
在终端里执行（确保你在项目 .venv 环境下）：

pip install poetry

（或者，如果你选择让 Poetry 在项目内创建虚拟环境，可先在父级设置 poetry config virtualenvs.in-project true，然后 poetry install；两种路径都能让 Poetry 工具进入项目环境。）

安装完成后，检查：

复制代码

.venv\Scripts\poetry.exe   ← 已出现，工具本地化完成

现在，Poetry 真正"住进"了项目环境，项目成为自包含单元，可拷贝、可迁移、可复现。

六、理论高潮（嵌入第 11 篇已用结论的镜像段）

现代工具（Poetry / uv / hatch）与传统 virtualenv + pip 的本质差异 ：

锁文件（poetry.lock / uv.lock / hatch.lock）规定了版本确定性，但这些文件必须由对应工具来解析与执行；锁文件本身并不是"可执行指令"。因此，若项目迁移后 .venv\Scripts 中没有对应工具的可执行文件（如 poetry.exe），激活环境并不能运行 poetry install，项目失去了"自我管理依赖状态"的能力，从而无法被真正迁移或复现。
EPGF 的判定标准 ：激活环境后，项目能否独立执行依赖管理命令？若不能，则尚未完成治理。(诗歌)

七、示例（最终工程结构示意）

复制代码

D:\Projects\demo_poetry_project\
├─ .venv\
│  ├─ Scripts\
│  │  ├─ python.exe
│  │  ├─ pip.exe
│  │  └─ poetry.exe    ← 已本地化，项目自包含
├─ pyproject.toml
├─ poetry.lock
└─ src\

八、几条实践性建议（EPGF 风格）

父级先统一安装 ：在 D:\A\envs\py311 等父级环境集中安装 Poetry（治理与版本控制）。
PyCharm 指定父级 poetry.exe ：新建项目时优先指定父级 poetry.exe 能保证创建步骤可控。(JetBrains)
执行项目本地化 ：进入项目终端（PyCharm 自动激活 .venv），运行 pip install poetry（或用 Poetry 的 in-project 配置创建虚拟环境并执行 poetry install）。
把 pyproject.toml 与 poetry.lock 一起纳入版本控制 ，但不要依赖它们单独完成迁移（必须有工具在环境内）。(JetBrains)

九、下一篇（完全同构）

下一篇我们将按相同逻辑写 EPGF 新手教程 13｜Hatch（GUI + 工具本地化） ：父级统一安装 → PyCharm 指定 → 创建环境 → 在项目 .venv 中 pip install hatch（或让 hatch 在项目内创建环境），同样把"工具本地化"作为必须步骤。

十、结语（给新手的一句话）

Poetry 给你版本与依赖的确定性，锁文件保证"用哪个版本"，但Poetry 本身必须在项目环境中才能"执行锁文件" 。EPGF 要求父级治理与项目级本地化两步并行：一次治理（方便维护），一次本地化（保证迁移/复现）。用 PyCharm 的 GUI 点几下，再在终端 pip install 一次，你就为将来换机、发给学生或传给同事铺好了"开箱即用"的路径。(JetBrains)

参考（官方）

PyCharm：Configure a Poetry environment. (JetBrains)
PyCharm：Use pyproject.toml (关于 PyCharm 如何创建/识别 pyproject.toml)。(JetBrains)
Poetry 官方文档：virtualenvs.in-project（Poetry 默认虚拟环境位置与 in-project 配置）。(诗歌)