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

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

EPGF 新手教程 11

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

副标题：uv 很快，但默认不自包含；EPGF 要的，是"迁移就能跑"的工程级保证。

开篇一句话（结论先行）

uv 是现代且高效的环境/依赖管理工具，PyCharm 已原生支持在创建项目时选择 uv 环境并生成 pyproject.toml；但 uv 的原生行为并不会把 uv.exe 放进项目的 .venv\Scripts ，因此在 EPGF 架构下，创建环境后必须在项目 .venv 中再执行工具本地化（pip install uv） ，否则锁文件与工具分离，项目不可复现也不可迁移。(JetBrains)

一、背景与前置（EPGF 已完成的治理）

EPGF 新手教程 00一次搭好、终身不乱：Windows Python 环境治理（EPGF）系列总览 / 阅读路线图
 EPGF 新手教程 01为什么 EPGF 能在一台 Windows 上，搞定所有虚拟环境？------一次搭好，终身不乱的 Python 环境治理逻辑（新手也能看懂）
EPGF 新手教程 02第一次安装就不踩坑：Anaconda 正确安装与路径一次性治理------把 Python 安装在 D:\A，从此不再折腾环境变量
 PGF 新手教程 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 是如何创建第一个"真正自包含"的项目环境的？

在第 01--10 篇中，你已完成：

把 Anaconda 安装到 D:\A，并建立版本层（如 D:\A\envs\py311）；
在父级 Python（版本层）中统一安装过管理工具（例如 pip install uv），此时父级工具的路径示例为 D:\A\envs\py311\Scripts\uv.exe；

这些步骤是 EPGF 的统一来源层，为可控创建打基础（非项目自包含）。

二、PyCharm 支持 uv 的要点（官方说明摘要）

PyCharm 从 2024.3.2 起支持配置 uv 环境；在创建新项目或为已有项目添加解释器时可选择 uv 作为环境类型，IDE 会为新项目自动生成 pyproject.toml。(JetBrains)
PyCharm 会尝试自动检测 已安装的 uv；若未检测到，可以手动指定 uv 可执行文件的位置（即父级 uv.exe）。(JetBrains)

以上信息来自 PyCharm 官方文档（已核验）。(JetBrains)

三、EPGF 下的正确 GUI 流程（逐步操作，中文界面）

前提：你已在父级 Python（示例 D:\A\envs\py311）中安装过 uv（即父级 uv.exe 存在）。

步骤 1 --- 新建项目

PyCharm → 文件 → 新建项目。

步骤 2 --- 环境类型：选择 uv

右侧【环境配置】区域：

环境类型 ：选择 uv（不是 venv/Conda/系统解释器）。
Python 解释器来源 ：选择 新建解释器 ，并指向父级解释器：
D:\A\envs\py311\python.exe。

说明：uv 环境必须寄生在某个父级 Python 上（EPGF 的版本层），父级负责"统一来源"。(JetBrains)

步骤 3 --- 指定父级 uv.exe（若未被自动检测）

PyCharm 会尝试检测 uv；若未检测成功，请手动浏览并指定父级 uv 可执行文件路径，例如：
D:\A\envs\py311\Scripts\uv.exe。

重点：此 uv.exe 是父级工具的来源 ，用于让 PyCharm 创建基于 uv 的项目环境（不是项目自带）。(JetBrains)

步骤 4 --- 确认环境位置与创建

保持 PyCharm 建议的项目环境路径（通常 <项目目录>\.venv），点击创建。PyCharm 将在项目目录下创建 .venv，绑定解释器并配置终端自动激活。(JetBrains)

四、创建后检查（你会看到"半成品"）

创建完成后，检查 .venv\Scripts（示例）：

复制代码

project/
└─ .venv/
   └─ Scripts/
      ├─ python.exe
      ├─ (通常没有 pip.exe ------ 这是 uv 的迭代后的默认行为)
      └─ (通常没有 uv.exe ------ 这是 uv 的默认行为)

说明：即便你用父级 uv 创建了环境，uv.exe 很可能还没有被复制进 .venv ，所以 .venv 处于"半成品"状态。(JetBrains)
uv venv 为何没有 pip？------ 揭秘现代 Python 工具链的"动态治理"挑战与 EPGF 的应对之道
 【笔记】加速 uv 安装：系统环境变量配置国内镜像源
 命令行创建 UV 环境及本地化实战演示------ 基于《Python 多版本与开发环境治理架构设计》的最佳实践
 使用 Conda 工具链创建 UV 本地虚拟环境全记录------基于《Python 多版本与开发环境治理架构设计》

五、EPGF 的关键动作：在 PyCharm 终端执行工具本地化（必做）

点击 PyCharm 下方 终端（Terminal） ，确认提示类似：
(.venv) PS D:\Projects\demo_uv_project> ------ 说明终端已自动激活项目 .venv（PyCharm 会自动激活）。(JetBrains)
在该终端执行（在 .venv 环境内）：

uv pip install uv
安装完成后，验证 .venv\Scripts 中出现 uv.exe：

.venv\Scripts\uv.exe

此刻项目已实现工具本地化 ：工具（uv）随项目 .venv 一起被包含、迁移与执行。

六、理论高潮

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

锁文件（如 uv.lock / poetry.lock / hatch.lock）确立的是版本确定性 ，但这些锁文件必须由相应工具解释并执行------也就是说，锁文件本身不是可执行脚本。

若项目拷贝到另一台机器后，.venv 中没有对应工具的可执行文件（如 uv.exe），激活 .venv 并不能执行 uv sync / poetry install / hatch env create，项目就失去了"自我管理依赖"的能力，因此无法被真正迁移或复现。

简言之：

锁文件解决版本确定性，工具本地化解决执行确定性；两者缺一不可。

（这一判断是 EPGF 的核心判定标准，亦是本系列一以贯之的规范。）

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

复制代码

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

八、后续与复用规则（这套逻辑适用于所有工具）

EPGF 的铁律：父级统一安装（治理） + 项目级本地化（复现） 。

对所有现代管理工具（uv、poetry、hatch、pipx、nox、tox 等）一视同仁：父级负责统一来源，项目级必须本地化（pip install <tool>），才能保证迁移、教学和复现的可靠性。

九、结语（对新手的话）

在 PyCharm（中文版）中只需用图形界面点几下，你就能完成 uv 环境的创建；但真正让这个项目"可以被拷走就跑"的，是你在 PyCharm 终端里执行的那一句：

复制代码

uv pip install uv

这是 EPGF 的工程哲学：花一点小功夫，多一步安装，换来长期的可控、可迁移、可复现。

参考（重要官方来源）

PyCharm 官方：Configure a uv environment（关于在 PyCharm 中配置 uv 的官方说明与注意事项）。(JetBrains)