【Python 环境管理】使用 uv 创建 Python 虚拟环境完整指南

作者：tudou_yu
发布日期：2026-07-19
操作系统：Windows
终端：CMD / PowerShell
适用场景：Python 项目开发、环境隔离、依赖管理

---

📌 前言

uv 是一个极速的 Python 包管理工具，可以替代 pip + virtualenv，速度更快、体验更好。本文将手把手教你如何从零开始，使用 uv 创建一个 Python 项目并配置虚拟环境。

---

📂 环境规划

项目	名称	路径
项目代码	RAG_project	D:\projects\RAG_project
虚拟环境	.venv	D:\projects\RAG_project\.venv（在项目内部）

设计理念：一个项目对应一个虚拟环境，保证依赖隔离，便于管理。

---

📋 目录

1. 安装 uv

2. 创建项目目录

3. 初始化 uv 项目

4. 配置镜像源

5. 锁定 Python 版本

6. 创建虚拟环境

7. 激活虚拟环境

8. 安装三方包

9. 同步环境生成锁文件

10. 退出虚拟环境

11. 配置 PyCharm

12. 常用命令速查表

---

1. 安装 uv（全局，只需一次）

所在目录：任意目录
是否在虚拟环境中：❌ 否（使用全局 Python）

📝 操作

打开 CMD 或 PowerShell，执行：

bash

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

✅ 验证安装

bash

uv -V

📤 预期输出

text

uv 0.11.23

💡 说明

• 使用阿里云镜像源加速下载

• uv 是全局工具，只需安装一次

• 如果已经安装，可跳过此步骤

---

2. 创建项目目录

所在目录：D:\
是否在虚拟环境中：❌ 否

📝 操作

bash

# 切换到 D 盘
D:

# 创建 projects 文件夹（如果没有）
mkdir projects

# 进入 projects 文件夹
cd projects

# 创建项目文件夹并进入
mkdir RAG_project
cd RAG_project

📤 当前路径

text

D:\projects\RAG_project>

💡 说明

建议将所有项目统一放在一个目录下（如 D:\projects\），便于管理。

---

3. 初始化 uv 项目

所在目录：D:\projects\RAG_project
是否在虚拟环境中：❌ 否（虚拟环境尚未创建）

📝 操作

bash

uv init --name RAG_project

📤 预期输出

text

Initialized project `RAG_project`

📂 生成的文件

text

D:\projects\RAG_project\
├── main.py              # 示例入口文件
├── pyproject.toml       # 项目配置文件
├── README.md            # 项目说明（空）
└── .python-version      # Python 版本记录

💡 说明

• uv init：初始化 uv 项目

• --name RAG_project：指定项目名称，会写入 pyproject.toml

---

4. 配置镜像源

所在目录：D:\projects\RAG_project
是否在虚拟环境中：❌ 否

📝 操作

用记事本打开 pyproject.toml：

bash

notepad pyproject.toml

在文件末尾添加以下内容：

toml

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

✅ 修改后完整内容

toml

[project]
name = "rag-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.10"
dependencies = []

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

保存并关闭（Ctrl+S → 关闭窗口）。

💡 说明

• [tool.uv]：uv 工具的专属配置区域

• index-url：指定 PyPI 镜像源，加速包下载

---

5. 锁定 Python 版本

所在目录：D:\projects\RAG_project
是否在虚拟环境中：❌ 否

📝 操作

bash

uv python pin 3.10.20

📤 预期输出

text

Pinned `.python-version` to `3.10.20`

✅ 验证

bash

type .python-version

📤 预期输出

text

3.10.20

💡 说明

• uv python pin：锁定项目使用的 Python 版本

• 如果本地没有该版本，uv 会自动下载

• 保证团队成员使用统一的 Python 版本

---

6. 创建虚拟环境

所在目录：D:\projects\RAG_project
是否在虚拟环境中：❌ 否

📝 操作

bash

uv venv

📤 预期输出

text

Using Python 3.10.20
Creating virtual environment at: .venv
Activate with: .venv\Scripts\activate

📂 生成的文件

text

D:\projects\RAG_project\
├── .venv/               # 虚拟环境目录 ✨ 新增
│   ├── Scripts/         # 激活脚本和可执行文件
│   ├── Lib/             # 三方包安装位置
│   └── pyvenv.cfg       # 环境配置文件
├── main.py
├── pyproject.toml
├── README.md
└── .python-version

💡 说明

• uv venv：在当前目录创建 .venv 虚拟环境

• 虚拟环境放在项目内部，删除项目时可一并清理

---

7. 激活虚拟环境

所在目录：D:\projects\RAG_project
是否在虚拟环境中：⚠️ 执行后进入（激活后即为虚拟环境）

📝 操作

CMD 用户：

bash

.venv\Scripts\activate.bat

PowerShell 用户：

bash

.venv\Scripts\Activate.ps1

📤 激活成功标志

CMD 中：

text

(rag-project) D:\projects\RAG_project>

PowerShell 中：

text

(rag-project) PS D:\projects\RAG_project>

✅ 验证当前 Python

bash

where python

📤 预期输出（第一条）

text

D:\projects\RAG_project\.venv\Scripts\python.exe

✅ 验证 Python 版本

bash

python --version

📤 预期输出

text

Python 3.10.20

✅ 查看虚拟环境路径

bash

echo %VIRTUAL_ENV%

📤 预期输出

text

D:\projects\RAG_project\.venv

💡 说明

• 命令行前缀 (rag-project) 表示虚拟环境已激活

• 此时所有 Python 操作都在虚拟环境中进行

• %VIRTUAL_ENV% 环境变量指向当前虚拟环境路径

---

8. 安装三方包

所在目录：D:\projects\RAG_project
是否在虚拟环境中：✅ 是

8.1 查看初始状态

bash

uv pip list

📤 预期输出

text

Package    Version
--------   -------
（空）

8.2 安装单个包

bash

uv add langchain==1.3.10

📤 预期输出

text

Resolved 36 packages in 10s
Installed 36 packages in 8s
 + langchain==1.3.10
 + ...（依赖包列表）

8.3 安装 setuptools（PyCharm 需要）

bash

uv add setuptools==79.0.1

📤 预期输出

text

 + setuptools==79.0.1

⚠️ 注意：版本必须为 79.0.1，更高版本 PyCharm 不兼容。

8.4 创建 requirements.txt 批量安装

创建 requirements.txt 文件：

bash

notepad requirements.txt

粘贴以下内容：

txt

langchain-openai==1.3.3
langchain-mcp-adapters==0.3.0
fastmcp==3.4.2
python-a2a==0.5.4

保存并关闭。

8.5 批量安装

bash

uv add -r requirements.txt

📤 预期输出

text

Resolved 132 packages in 2s
Installed 89 packages in 25s
 + aiofile==3.9.0
 + aiohttp==3.14.1
 + fastmcp==3.4.2
 + langchain-openai==1.3.3
 + ...（共 89 个包）

8.6 查看所有已安装的包

bash

uv pip list

📤 预期输出（部分）

text

Package                   Version
------------------------- -----------
aiofile                   3.9.0
fastmcp                   3.4.2
langchain                 1.3.10
langchain-openai          1.3.3
setuptools                79.0.1
...（共 89 个包）

💡 说明

命令	用途
uv add 包名==版本	安装指定版本的包
uv add -r requirements.txt	批量安装
uv pip list	查看所有已安装包
uv pip show 包名	查看某个包的详情

---

9. 同步环境生成 uv.lock

所在目录：D:\projects\RAG_project
是否在虚拟环境中：✅ 是

📝 操作

bash

uv sync

📤 预期输出

text

Resolved 132 packages in 2s
Audited 89 packages in 1s

📂 新增文件

text

D:\projects\RAG_project\
├── .venv/
├── uv.lock              # ✨ 新增：依赖锁文件
├── pyproject.toml
├── requirements.txt
├── main.py
├── README.md
└── .python-version

💡 说明

• uv.lock 记录所有依赖包的精确版本号、哈希值和来源信息

• 保证团队成员或部署环境安装完全一致的依赖

• 类似于 npm 的 package-lock.json

---

10. 退出虚拟环境

所在目录：任意目录
是否在虚拟环境中：⚠️ 执行后退出

📝 操作

bash

deactivate

📤 激活状态变化

退出前：

text

(rag-project) D:\projects\RAG_project>

退出后：

text

D:\projects\RAG_project>

---

11. 配置 PyCharm

是否在虚拟环境中：❌ 否（PyCharm 界面操作）

📝 操作步骤

步骤 1：打开项目

启动 PyCharm → 点击 Open → 选择 D:\projects\RAG_project

步骤 2：打开设置

File → Settings（或快捷键 Ctrl + Alt + S）

步骤 3：找到 Python 解释器

Project: RAG_project → Python Interpreter

步骤 4：添加现有解释器

点击齿轮图标 ⚙️ → Add Interpreter... → Existing

步骤 5：选择虚拟环境的 Python

选择路径：

text

D:\projects\RAG_project\.venv\Scripts\python.exe

步骤 6：确认配置

点击 OK，等待索引完成。

✅ 配置成功标志

在 Python Interpreter 页面显示：

text

Python 3.10.20 (rag-project)

已安装的包列表会显示所有依赖。

💡 说明

• PyCharm 需要使用 setuptools 解析 Python 环境

• 如未安装 setuptools，PyCharm 可能无法正常识别

---

12. 常用命令速查表

12.1 项目初始化

操作	命令	所在目录
安装 uv	pip install uv -i 镜像源	任意
创建项目	mkdir 项目名 && cd 项目名	目标位置
初始化项目	uv init --name 项目名	项目目录
配置镜像源	编辑 pyproject.toml 添加 [tool.uv]	项目目录
锁定 Python	uv python pin 3.10.20	项目目录
创建虚拟环境	uv venv	项目目录

12.2 虚拟环境管理

操作	命令	所在目录
激活环境（CMD）	.venv\Scripts\activate.bat	项目目录
激活环境（PowerShell）	.venv\Scripts\Activate.ps1	项目目录
退出环境	deactivate	任意
查看 Python 路径	where python	任意
查看虚拟环境路径	echo %VIRTUAL_ENV%	任意

12.3 包管理

操作	命令	要求
安装单个包	uv add 包名==版本	项目目录 + 环境激活
批量安装	uv add -r requirements.txt	项目目录 + 环境激活
同步环境	uv sync	项目目录 + 环境激活
查看所有包	uv pip list	项目目录 + 环境激活
查看某个包	uv pip show 包名	项目目录 + 环境激活

---

📁 最终目录结构

text

D:\projects\RAG_project\
│
├── .venv/                         ← 虚拟环境
│   ├── Scripts/
│   │   ├── activate.bat           ← CMD 激活脚本
│   │   ├── Activate.ps1           ← PowerShell 激活脚本
│   │   ├── python.exe             ← 虚拟环境 Python
│   │   └── pip.exe
│   ├── Lib/
│   │   └── site-packages/         ← 三方包安装目录
│   └── pyvenv.cfg
│
├── pyproject.toml                 ← 项目配置 + 镜像源
├── uv.lock                        ← 依赖锁文件
├── requirements.txt               ← 依赖清单（可选）
├── main.py                        ← 入口文件
├── README.md                      ← 项目说明
└── .python-version                ← Python 版本

---

🚀 新建项目快速版

创建新项目时，只需三步：

bash

# 1. 创建并进入项目目录
mkdir D:\projects\新项目 && cd D:\projects\新项目

# 2. 初始化 + 创建环境
uv init --name 新项目
uv venv

# 3. 激活 + 安装包
.venv\Scripts\activate
uv add 你需要的包

---

📝 总结

要点	说明
✅ 一个项目一个环境	保证依赖隔离，互不干扰
✅ 虚拟环境放在项目内	删除项目时一并清理，干净整洁
✅ 使用 uv 管理依赖	速度快，自动生成锁文件
✅ 配置镜像源	显著提升下载速度
✅ 锁定 Python 版本	保证团队环境一致
✅ uv.lock 提交到仓库	保证部署环境精确复现

---

🔗 参考资料

• uv 官方文档

• PyPI 镜像源