（保姆级）UV虚拟环境搭建全流程：安装、依赖管理、PyCharm配置

（保姆级）UV虚拟环境搭建全流程：安装、依赖管理、PyCharm配置

下一代Python虚拟环境与包管理工具实战指南

作者：秀£
发布日期：2026-08-14
操作系统：Windows
适用场景：使用 uv 快速创建 Python 虚拟环境，并配置 PyCharm 进行项目开发

---

uv 环境管理工具

对于 Python 环境中三方包依赖冲突的情况，以及安装新包因为依赖导致旧包版本发生变化的情况，uv 作为新一代的 Python 环境管理工具，挺身而出。无论是 Python 自带的 venv，还是著名的 conda，都无法从根本上直接做到【新包不碰旧包、间接依赖不会被卸载】的效果，uv 做到了：

• 原有已安装包版本固定不变；新包会自动匹配能兼容当前所有旧包的最高正式版本；只有在执行 uv lock --upgrade 命令时，才会全局升级所有包到各自最高兼容版本。
• 依赖包的依赖不能直接被卸载，只有卸载直接依赖、且间接依赖不被其他依赖所依赖的时候，间接依赖才会被一起自动卸载。

一句话总结：uv = 包安装器 + 依赖解析器 + 虚拟环境管理器，三合一，速度快到飞起。

---

一、安装 uv

以 Windows CMD 终端为例，用 uv 搭建 Python 虚拟环境，首先要安装 uv。注意：请用当前全局的 Python（非虚拟环境）来安装 uv（如果已经安装了 uv，跳过本步骤）。

cmd 终端

安装 uv 虚拟环境包管理工具（代替 pip 和虚拟环境）

pip install uv -i https://mirrors.aliyun.com/pypi/simple/

验证安装：

# 查看 uv 版本
uv -V

看到类似 uv 0.x.x 的输出版本号，说明安装成功。

⚠️ 提示：如果提示 'uv' 不是内部或外部命令，说明 Python 的 Scripts 目录（如 C:\Users\用户名\AppData\Local\Programs\Python\Python310\Scripts）没加入 PATH 环境变量，手动添加后重新打开终端即可。

---

二、初始化项目

在你想存放虚拟环境的文件夹中打开 CMD（例如 `D:\All_Projects\test_venv），然后执行初始化命令：

uv init --name myproject

--name myproject 是自定义项目名称，项目名称可随意指定。

初始化后，目录下会生成以下文件：

• pyproject.toml —— 项目配置文件（uv 的核心，依赖都记录在这里）
• README.md —— 项目说明文件
• 后续会生成 .venv 和 uv.lock

---

三、配置镜像源

打开 pyproject.toml 文件，在末尾添加以下内容，指定阿里云镜像源：

[tool.uv]
index-url = "https://mirrors.aliyun.com/pypi/simple/"

这样后续安装三方包时会快很多。（如果你使用其他镜像，如清华源，替换链接即可。）

---

四、创建虚拟环境

锁定 Python 版本（假设你使用 3.10 系列，uv 会自动下载并锁定该版本）：

uv python pin 3.10

创建虚拟环境：

uv venv --clear
uv sync

执行完成后，当前目录下会生成：

• .venv/ —— 虚拟环境目录
• uv.lock —— 依赖锁定文件（保证任何人在任何机器上装出的环境完全一致）

虚拟环境的 Python 解释器路径为：

.venv\Scripts\python.exe

---

五、安装依赖

注意：所有 uv add 命令必须在包含 pyproject.toml 的目录下执行。

5.1 安装单个包

uv add langchain

uv 会自动解析并安装该包及其所有依赖，同时写入 pyproject.toml 的依赖列表。需要指定版本时：

uv add langchain==1.3.10

⚠️ 特别提醒：建议安装 setuptools（项目可能不用，但 PyCharm 解析 Python 环境依赖它）：

uv add setuptools==79.0.1

如果遇到 PyCharm 无法识别解释器的问题，可将 setuptools 固定到较低版本（如 uv add "setuptools==79.0.1"）后重试，过高版本可能导致PyCharm无法识别。

5.2 批量安装依赖

在 pyproject.toml 同级目录下创建 requirements.txt，内容示例（换成你项目的依赖即可）：

numpy==1.26.4
pandas==2.2.2
requests==2.32.3

然后执行批量安装：

uv add -r requirements.txt

uv 会智能处理依赖关系，新包不会影响已安装的旧包。

---

六、配置 PyCharm

1. 打开 PyCharm → Settings → Project → Python Interpreter
2. 点击右上角齿轮图标 → Add
3. 选择 Existing environment
4. 浏览并选择虚拟环境中的解释器（.venv\Scripts\python.exe）
   

配置完成后，PyCharm 即可使用该虚拟环境中的所有依赖包。

---

七、验证运行

环境搭好了，怎么确认真的能用？这一节带你亲手跑一个程序，按下面 4 步走，每一步都写了具体操作，跟着做就行。

第 1 步：创建一个测试脚本 main.py

在项目文件夹 myproject 里（和 pyproject.toml 同一个目录），新建一个文件，命名为 main.py。

不会新建？两种方法任选：

方法一：用记事本

1. 打开项目文件夹 myproject
2. 右键空白处 → 新建 → 文本文档
3. 把文件名 新建文本文档.txt 改成 main.py（如果系统提示"如果改变文件扩展名，可能会导致文件不可用"，点是即可）
4. 右键 main.py → 打开方式 → 记事本，粘贴下面的代码，Ctrl + S 保存

方法二：用 PyCharm

1. 用 PyCharm 打开 myproject 文件夹（File → Open）
2. 左侧项目树里右键 → New → Python File → 输入 main，回车
3. 粘贴下面的代码，Ctrl + S 保存

代码内容（复制全部）：

import requests
import numpy as np

print("虚拟环境运行成功！")
print("requests 版本：", requests.__version__)
print("numpy 版本：", np.__version__)

第 2 步：在项目目录打开命令行

关键：必须要在 myproject 文件夹里打开命令行，否则运行时会提示找不到文件。

最简单的方法：

1. 打开 myproject 文件夹
2. 点击顶部地址栏（显示路径的那一栏），删掉原有内容，输入 cmd，按回车
3. 弹出的黑色窗口就是命令行，它的提示符应该显示为 ...\myproject>——最后的 > 表示"你现在就在这个目录下"

第 3 步：运行命令

在命令行里输入下面的命令，按回车：

uv run python main.py

这条命令怎么理解？

• uv run：用当前项目的虚拟环境来运行（不需要手动激活环境，uv 自动搞定）
• python main.py：让 Python 执行 main.py 这个文件

第 4 步：看结果

• ✅ 看到三行输出（“虚拟环境运行成功！” + 两个版本号），说明环境搭建完全成功，可以进入下一节了！
• ❌ 提示 No such file or directory 或找不到 main.py：说明命令行不在项目目录，回到第 2 步重新打开
• ❌ 提示 'uv' 不是内部或外部命令：说明 uv 没装好，回到第一节重装

以后运行你自己的项目，套路完全一样：命令行切到项目目录，执行 uv run python 你的入口文件.py 即可。

如果不想用命令行，也可以直接用 PyCharm：配好解释器后（见第六节），在 PyCharm 里打开 main.py，右键 → Run ‘main’，效果相同。

---

八、常见问题

Q1：安装时网络超时 / 下载慢？
A：确认已在 pyproject.toml 中配置镜像源（见第三节），或在命令后追加 -i https://mirrors.aliyun.com/pypi/simple/。

Q2：uv 不是内部或外部命令？
A：Python 的 Scripts 目录未加入 PATH，手动添加后重新打开终端；或使用 python -m uv 调用。

Q3：uv python pin 提示找不到 Python 版本？
A：先执行 uv python install 3.10 让 uv 自动下载对应版本，再执行 uv python pin 3.10。

Q4：PyCharm 无法识别 .venv 解释器？
A：多半是 setuptools 版本问题，参考 5.1 节将 setuptools 固定到较低版本；并确认解释器路径选择的是 .venv\Scripts\python.exe（不是项目根目录）。

---

九、最终目录结构

D:\All_Projects\myproject/
├── .venv/                  # 虚拟环境目录
│   └── Scripts/
│       └── python.exe      # 虚拟环境的 Python 解释器
├── pyproject.toml          # 项目配置 + 依赖声明
├── uv.lock                 # 依赖锁定文件
├── requirements.txt        # 依赖清单（可选）
├── main.py                 # 项目入口脚本
└── README.md

---

结语

到此，uv 虚拟环境已全部搭建完成。uv 的优势在于：

• ⚡ 极快的安装速度（Rust 编写，比 pip 快 10~100 倍）
• 📦 统一的 pyproject.toml 管理
• 🔒 精准的依赖锁定（uv.lock）
• 🧹 清晰的虚拟环境隔离

赶快试试吧，告别 pip + venv 的繁琐组合，拥抱更高效的开发体验！

---

📌 本文首发于 CSDN，转载请注明出处。
如有问题，欢迎在评论区交流讨论。