（保姆级教程）【Python 环境管理】(详细版)使用 uv 创建 Python 虚拟环境完整指南

ssslllsss1

476人浏览 · 2026-07-19 16:18:13

ssslllsss1 · 2026-07-19 16:18:13 发布

【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`（在项目内部）

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

📋 目录

安装 uv
创建项目目录
初始化 uv 项目
配置镜像源
锁定 Python 版本
创建虚拟环境
激活虚拟环境
安装三方包
同步环境生成锁文件
退出虚拟环境
配置 PyCharm
常用命令速查表

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 提交到仓库	保证部署环境精确复现