当前位置：首页>python>Python 新一代包管理工具 uv

Python 新一代包管理工具 uv

2026-06-29 13:18:41

Python 新一代包管理工具 uv

TECH · NOTES

Python 新一代包管理工具
uv 入门实战指南

阅读 8 min

一、前言

作为一名 Python 开发者，你一定经历过这样的痛苦：

✔pip install 慢得让人怀疑人生

✔ 虚拟环境管理混乱，不同项目依赖冲突

✔requirements.txt 锁不住版本，"在我电脑上能跑"成为常态

⚡ 重点结论

如果你正在被这些问题困扰，那么 uv 就是你的救星。

02	/ 二、uv 是什么？

uv 是由 Astral 团队（就是开发 ruff 的那帮人）用 Rust 编写的 Python 包管理工具。它的定位是：

❝ 引用块

一个工具，替代 pip、pip-tools、virtualenv、pyenv、poetry、pdm。

# 2.1 核心优势

特性	uv	pip	poetry
安装速度	极快（Rust 实现）	慢	中等
依赖解析	快速且准确	一般	较慢
锁文件	自动生成 uv.lock	无	poetry.lock
Python 版本管理	内置	无	无
虚拟环境管理	自动	手动	自动
兼容性	兼容 pip/requirements.txt	-	独立生态

# 2.2 性能对比

官方 benchmark 数据：

✔ 比 pip 快 10-100 倍

✔ 比 poetry 快 10-50 倍

✔ 比 pip-tools 快 10-80 倍

三、安装 uv

# 3.1 Windows 安装

</> powershell

01# 方式一：官方脚本（推荐）

02powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

04# 方式二：pip 安装

05pip install uv

07# 方式三：scoop 安装

08scoop install uv

# 3.2 macOS / Linux 安装

</> bash

01# 方式一：官方脚本（推荐）

02curl -LsSf https://astral.sh/uv/install.sh | sh

04# 方式二：pip 安装

05pip install uv

07# 方式三：brew 安装

08brew install uv

# 3.3 验证安装

</> bash

01uv --version

02# 输出示例：uv 0.x.x

04	/ 四、项目实战：新能源电力系统平台

接下来，我们以实际项目「极端天气识别与供电韧性评估平台」为例，演示 uv 的完整工作流。

# 4.1 项目结构

</> 代码块

01new-energy-platform/

02├── .python-version # Python 版本锁定

03├── .venv/ # uv 自动创建的虚拟环境

04├── pyproject.toml # 项目配置和依赖声明

05├── uv.lock # 依赖锁文件（自动生成）

06├── .env # 环境变量（不入 Git）

07├── .env.example # 环境变量模板

08├── run.py # 应用入口

09├── app/ # Flask 应用代码

10│ ├── __init__.py

11│ ├── api/ # API 路由

12│ ├── config.py # 配置类

13│ ├── extensions.py # Flask 扩展

14│ ├── models/ # 数据库模型

15│ ├── services/ # 业务逻辑

16│ └── tasks/ # 定时任务

17├── ml/ # 机器学习模块

18│ ├── config/ # 规则配置

19│ └── models/ # 训练好的模型

20├── scripts/ # SQL 脚本

21└── tests/ # 测试代码

# 4.2 核心配置文件解析

# pyproject.toml — 项目身份证

</> toml

01[project]

02name = "new-energy-platform"

03version = "0.1.0"

04description = "新能源平台"

05readme = "README.md"

06requires-python = ">=3.11"

07dependencies = [

08 "apscheduler>=3.11.2", # 定时任务调度

09 "flask>=3.1.3", # Web 框架

10 "flask-sqlalchemy>=3.1.1", # ORM

11 "joblib>=1.5.3", # 模型序列化

12 "numpy>=2.4.6", # 数值计算

13 "pandas>=3.0.3", # 数据处理

14 "pymysql>=1.2.0", # MySQL 驱动

15 "python-dotenv>=1.2.2", # 环境变量

16 "scikit-learn>=1.9.0", # 机器学习

17]

19[project.scripts]

20serve = "run:app.run"

22[build-system]

23requires = ["hatchling"]

24build-backend = "hatchling.build"

⚡ 重点结论

关键字段说明：

✔requires-python：声明项目需要的 Python 版本

✔dependencies：项目依赖列表，支持版本约束

✔project.scripts：定义命令行入口

# .python-version — Python 版本锁定

</> 代码块

013.11

这个文件告诉 uv：本项目使用 Python 3.11。uv 会自动下载并管理对应版本。

# uv.lock — 依赖锁文件

这个文件由 uv 自动生成，记录了所有依赖的精确版本和哈希值，确保团队成员和部署环境使用完全一致的依赖版本。

⚡ 重点结论

重要提示：** uv.lock 应该提交到 Git！

05	/ 五、uv 常用命令

# 5.1 项目初始化

</> bash

01# 创建新项目

02uv init my-project

04# 在已有项目中初始化

05cd existing-project

06uv init

# 5.2 Python 版本管理

</> bash

01# 查看可用的 Python 版本

02uv python list

04# 安装指定版本的 Python

05uv python install 3.11

07# 固定项目使用的 Python 版本

08uv python pin 3.11

# 5.3 依赖管理

</> bash

01# 添加依赖

02uv add flask

03uv add flask numpy pandas

05# 添加开发依赖（不会打包到生产环境）

06uv add pytest --dev

08# 移除依赖

09uv remove flask

11# 更新依赖

12uv lock --upgrade

14# 同步环境（安装 uv.lock 中的所有依赖）

15uv sync

# 5.4 运行命令

</> bash

01# 在虚拟环境中运行 Python

02uv run python run.py

04# 运行项目脚本

05uv run serve

07# 运行测试

08uv run pytest

# 5.5 工具运行

</> bash

01# 临时运行工具（无需安装）

02uvx ruff check .

03uvx black --check .

04uvx mypy .

06	/ 六、uv vs 传统工具对比

# 6.1 传统 pip 工作流

</> bash

01# 1. 创建虚拟环境

02python -m venv .venv

04# 2. 激活虚拟环境

05source .venv/bin/activate # Linux/Mac

06.venv\Scripts\activate # Windows

08# 3. 安装依赖

09pip install -r requirements.txt

11# 4. 添加新依赖

12pip install flask

13pip freeze > requirements.txt

15# 5. 运行程序

16python run.py

# 6.2 uv 工作流

</> bash

01# 1. 初始化项目（自动创建虚拟环境）

02uv init

04# 2. 添加依赖（自动更新 pyproject.toml 和 uv.lock）

05uv add flask

07# 3. 运行程序（自动激活虚拟环境）

08uv run python run.py

⚡ 重点结论

对比发现：** uv 把 5 步简化为 3 步，且无需手动管理虚拟环境。

07	/ 七、常见问题 FAQ

# Q1: uv 和 pip 可以共存吗？

可以。uv 完全兼容 pip，你可以在同一个系统中同时使用。但建议一个项目统一使用一种工具。

# Q2: 已有的 requirements.txt 怎么迁移？

</> bash

01# uv 可以直接从 requirements.txt 导入

02uv add -r requirements.txt

# Q3: uv.lock 和 poetry.lock 有什么区别？

功能类似，都是锁文件。但 uv.lock 的生成速度更快，且格式更紧凑。

# Q4: .venv 目录需要提交到 Git 吗？

不需要。在 .gitignore 中添加 .venv/ 即可。团队成员通过 uv sync 即可还原环境。

# Q5: uv 支持私有源吗？

支持。在 pyproject.toml 中配置：

</> toml

01[tool.uv]

02index-url = "https://mirrors.aliyun.com/pypi/simple/"

八、最佳实践

# 8.1 项目初始化 Checklist

</> bash

01# 1. 初始化项目

02uv init

04# 2. 固定 Python 版本

05uv python pin 3.11

07# 3. 添加依赖

08uv add flask numpy pandas scikit-learn

10# 4. 添加开发依赖

11uv add pytest ruff --dev

13# 5. 提交到 Git

14git add pyproject.toml uv.lock .python-version

15git commit -m "chore: 初始化 uv 项目配置"

# 8.2 团队协作规范

1	pyproject.toml 和 uv.lock 必须提交到 Git
2	.venv/ 必须加入 `.gitignore`
3	新成员加入项目后，执行 `uv sync` 即可还原完整环境
4	添加新依赖时，使用 `uv add` 而非手动修改 `pyproject.toml`

# 8.3 CI/CD 集成

</> yaml

01# GitHub Actions 示例

02- name: Install uv

03 uses: astral-sh/setup-uv@v3

05- name: Install dependencies

06 run: uv sync

08- name: Run tests

09 run: uv run pytest

九、总结

uv 的出现，让 Python 的包管理体验向前迈进了一大步。对于习惯了 Java Maven/Gradle 的开发者来说，uv 提供了类似的「声明式依赖 + 锁文件」机制，让 Python 项目的依赖管理变得更加可靠和高效。

⚡ 重点结论

核心要点：

1	`pyproject.toml` 声明依赖，类似 `pom.xml`
2	`uv.lock` 锁定版本，类似 `pom.xml` 中的 dependencyManagement
3	`.python-version` 固定 Python 版本
4	`uv sync` 安装所有依赖
5	`uv run` 在虚拟环境中运行命令