uv Python 环境管理笔记

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：

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：

uv python install 3.12

查看：

uv python list

删除：

uv python uninstall 3.12

---

5. 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. 创建项目

进入项目目录：

mkdir my-project

cd my-project

初始化：

uv init

生成：

my-project
 |
 ├── pyproject.toml
 └── README.md

---

7. pyproject.toml 是什么？

pyproject.toml 是 Python 项目的核心配置文件。

类似：

语言	配置文件
Python	pyproject.toml
JavaScript	package.json
Rust	Cargo.toml
Java	pom.xml

它记录：

• 项目名称
• Python版本要求
• 项目依赖
• 工具配置

例如：

[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. 创建虚拟环境

默认：

uv venv

指定 Python：

uv venv --python 3.11

生成：

project

├── pyproject.toml

└── .venv

---

10. 激活虚拟环境

Windows PowerShell：

.\.venv\Scripts\Activate.ps1

退出：

deactivate

---

11. 安装依赖

添加项目依赖（推荐）

例如：

uv add requests

会：

1. 下载包
2. 安装到 .venv
3. 修改 pyproject.toml

例如：

dependencies = [
    "requests"
]

---

添加多个：

uv add numpy pandas

---

删除：

uv remove requests

---

12. uv.lock 文件

完整项目通常：

project

├── pyproject.toml

├── uv.lock

└── .venv

区别：

pyproject.toml

描述：

我需要什么

例如：

numpy
pandas
torch

---

uv.lock

描述：

实际安装了什么版本

例如：

numpy==2.1.0
pandas==2.2.3
torch==2.5.1

作用：

保证别人安装时环境完全一致。

---

13. 安装项目依赖

拿到别人项目：

project

├── pyproject.toml

└── uv.lock

执行：

uv sync

uv 自动：

1. 创建 .venv
2. 安装 Python
3. 安装所有依赖

---

14. 运行项目

推荐：

uv run main.py

例如：

uv run python app.py

不用手动激活环境。

---

15. uv 和缓存机制

uv 不会每个项目重复下载。

例如：

项目 A：

uv add numpy

下载：

numpy

保存：

uv cache

项目 B：

uv add numpy

发现缓存已有：

直接使用。

---

缓存位置：

查看：

uv cache dir

一般：

C:\Users\用户名\AppData\Local\uv\cache

---

清理缓存：

uv cache clean

---

16. 查看安装包

查看：

uv pip list

查看某个包：

uv pip show numpy

---

17. uv 临时运行工具

例如：

uvx ruff

效果：

1. 临时安装
2. 执行
3. 不污染环境

类似：

npm npx

---

18. requirements.txt 兼容

导出：

uv pip freeze > requirements.txt

安装：

uv pip install -r requirements.txt

---

19. Git 项目建议

推荐提交：

project

├── pyproject.toml
├── uv.lock
└── src

不要提交：

.venv/

.gitignore：

.venv/

原因：

虚拟环境可以通过：

uv sync

重新生成。

---

20. 推荐项目结构

D:\code

├── leetcode
│
│   ├── pyproject.toml
│   ├── uv.lock
│   └── .venv
│
├── ai-project
│
│   ├── pyproject.toml
│   ├── uv.lock
│   └── .venv
│
└── backend-project
    |
    ├── pyproject.toml
    ├── uv.lock
    └── .venv

---

21. 常用命令速查

Python管理

uv python list

uv python install 3.12

uv python uninstall 3.12

项目初始化

uv init

虚拟环境

uv venv

uv venv --python 3.11

添加依赖

uv add package

uv remove package

同步环境

uv sync

运行

uv run python main.py

查看包

uv pip list

缓存

uv cache dir

uv cache clean

---

22. 从 Miniforge 迁移到 uv

旧方式：

Miniforge

├── base
├── env1
├── env2
└── pkgs

新方式：

uv

Python版本管理

        +

项目独立 .venv

        +

共享缓存

适合：

• LeetCode
• Python开发
• AI应用
• 后端项目

---

总结

现代 Python 推荐流程：

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 的集合。