uv Python 环境管理
1. uv 是什么？
uv 是一个现代 Python 项目管理工具，由 Astral 公司开发。
它可以替代：
- pip（安装 Python 包）
- venv（创建虚拟环境）
- pyenv（管理 Python 版本）
- Poetry（项目依赖管理）
核心特点：
- 速度快（Rust 编写）
- 自动管理 Python 版本
- 自动创建虚拟环境
- 项目级依赖隔离
- 全局缓存，避免重复下载
2. uv 和传统 Python 环境区别
传统方式
通常：
Python
|
├── pip install numpy
|
└── 全局环境问题：
不同项目依赖容易冲突。
例如：
项目 A：
django==4.2
numpy==1.26项目 B：
django==5.0
numpy==2.0如果安装到全局 Python：
Python
|
├── django 4.2
└── django 5.0 ❌ 冲突uv 推荐方式
每个项目独立：
projectA
|
├── pyproject.toml
└── .venv
projectB
|
├── pyproject.toml
└── .venv每个项目拥有自己的：
- Python 环境
- 第三方包
- 依赖版本
3. uv 不需要提前安装 Python
uv 可以自己管理 Python。
查看已有 Python：
powershell
uv python list例如：
cpython-3.11.14-windows-x86_64-none
AppData\Roaming\uv\python\cpython-3.11.14表示：
已经安装：
Python 3.11.14其他：
<download available>表示：
可以下载，但目前没有安装。
4. 安装 Python
安装 Python 3.12：
powershell
uv python install 3.12查看：
powershell
uv python list删除：
powershell
uv python uninstall 3.125. uv Python 存储位置
默认：
C:\Users\用户名\AppData\Roaming\uv\python例如：
uv
└── python
└── cpython-3.11.14
└── python.exe多个 Python 版本会共存：
Python 3.11
Python 3.12
Python 3.13但是只占用几百 MB。
6. 创建项目
进入项目目录：
powershell
mkdir my-project
cd my-project初始化：
powershell
uv init生成：
my-project
|
├── pyproject.toml
└── README.md7. pyproject.toml 是什么？
pyproject.toml 是 Python 项目的核心配置文件。
类似：
| 语言 | 配置文件 |
|---|---|
| Python | pyproject.toml |
| JavaScript | package.json |
| Rust | Cargo.toml |
| Java | pom.xml |
它记录：
- 项目名称
- Python版本要求
- 项目依赖
- 工具配置
例如：
toml
[project]
name = "my-project"
requires-python = ">=3.11"
dependencies = [
"requests",
"numpy"
]8. .venv 是什么？
.venv 是项目自己的虚拟环境。
结构：
project
|
├── pyproject.toml
|
└── .venv
|
├── Scripts
│ └── python.exe
|
└── Lib
└── site-packages
├── numpy
└── pandas里面包含：
- Python解释器
- 第三方库
9. 创建虚拟环境
默认：
powershell
uv venv指定 Python：
powershell
uv venv --python 3.11生成：
project
├── pyproject.toml
└── .venv10. 激活虚拟环境
Windows PowerShell：
powershell
.\.venv\Scripts\Activate.ps1退出：
powershell
deactivate11. 安装依赖
添加项目依赖（推荐）
例如：
powershell
uv add requests会：
- 下载包
- 安装到 .venv
- 修改 pyproject.toml
例如：
toml
dependencies = [
"requests"
]添加多个：
powershell
uv add numpy pandas删除：
powershell
uv remove requests12. uv.lock 文件
完整项目通常：
project
├── pyproject.toml
├── uv.lock
└── .venv区别：
pyproject.toml
描述：
我需要什么
例如：
numpy
pandas
torchuv.lock
描述：
实际安装了什么版本
例如：
numpy==2.1.0
pandas==2.2.3
torch==2.5.1作用：
保证别人安装时环境完全一致。
13. 安装项目依赖
拿到别人项目：
project
├── pyproject.toml
└── uv.lock执行：
powershell
uv syncuv 自动：
- 创建 .venv
- 安装 Python
- 安装所有依赖
14. 运行项目
推荐：
powershell
uv run main.py例如：
powershell
uv run python app.py不用手动激活环境。
15. uv 和缓存机制
uv 不会每个项目重复下载。
例如：
项目 A：
uv add numpy下载：
numpy保存：
uv cache项目 B：
uv add numpy发现缓存已有：
直接使用。
缓存位置：
查看：
powershell
uv cache dir一般：
C:\Users\用户名\AppData\Local\uv\cache清理缓存：
powershell
uv cache clean16. 查看安装包
查看：
powershell
uv pip list查看某个包：
powershell
uv pip show numpy17. uv 临时运行工具
例如：
powershell
uvx ruff效果：
- 临时安装
- 执行
- 不污染环境
类似：
npm npx18. requirements.txt 兼容
导出：
powershell
uv pip freeze > requirements.txt安装：
powershell
uv pip install -r requirements.txt19. Git 项目建议
推荐提交：
project
├── pyproject.toml
├── uv.lock
└── src不要提交：
.venv/.gitignore：
.venv/原因：
虚拟环境可以通过：
powershell
uv sync重新生成。
20. 推荐项目结构
D:\code
├── leetcode
│
│ ├── pyproject.toml
│ ├── uv.lock
│ └── .venv
│
├── ai-project
│
│ ├── pyproject.toml
│ ├── uv.lock
│ └── .venv
│
└── backend-project
|
├── pyproject.toml
├── uv.lock
└── .venv21. 常用命令速查
Python管理
powershell
uv python list
uv python install 3.12
uv python uninstall 3.12项目初始化
powershell
uv init虚拟环境
powershell
uv venv
uv venv --python 3.11添加依赖
powershell
uv add package
uv remove package同步环境
powershell
uv sync运行
powershell
uv run python main.py查看包
powershell
uv pip list缓存
powershell
uv cache dir
uv cache clean22. 从 Miniforge 迁移到 uv
旧方式：
Miniforge
├── base
├── env1
├── env2
└── pkgs新方式：
uv
Python版本管理
+
项目独立 .venv
+
共享缓存适合：
- LeetCode
- Python开发
- AI应用
- 后端项目
总结
现代 Python 推荐流程：
powershell
uv init
uv venv
uv add package
uv run main.py核心理解：
pyproject.toml→ 项目需要什么uv.lock→ 固定具体版本.venv→ 项目自己的运行环境- uv cache → 多项目共享下载缓存
- uv python → 管理 Python 解释器
uv = Python 项目的 npm + nvm + venv 的集合。