uv · Python Tooling

uv Python 包管理完全指南

Astral 出品,Rust 写的下一代 Python 工具链——10-100 倍速度,一键替代 pip、venv、pipx、poetry、pyenv

安装极快
统一工具链
锁文件可重现
多版本 Python
CI/CD 友好
10× pip 速度
10 核心章节
Rust 原生实现

为什么今天每个 Python 开发者都该切换到 uv?

过去十年 Python 包管理一直是生态最大的痛点——pip 慢、依赖解析弱、虚拟环境要手动管理、Poetry 配置复杂、Conda 和 pip 互相打架。uv 是 Astral(Ruff 作者团队)用 Rust 重写的全新工具链,一次性把 pip、venv、pipx、poetry、pyenv 的功能全部合并,速度比 pip 快 10-100 倍。

更重要的是 uv 把 Python 生态"锁文件 + 工作区"这些现代语言早就有的能力补齐了:uv.lock 保证团队和 CI 装出的包完全一致;uv runnpm run 一样执行脚本;uv toolpipx 一样全局安装工具。2024 年起 FastAPI、Polars、Hugging Face 等项目陆续迁移到 uv 作为推荐工作流。

本教程从零开始讲到进阶:安装和核心命令、pyproject.toml 与锁文件、虚拟环境管理、Python 版本切换、工具管理、工作区 Monorepo、脚本模式、PyTorch 等深度学习框架集成、CI/CD 部署、迁移指南。

核心能力

六大能力一览,理解 uv 为何能一统 Python 工具链

🚀

极致速度

Rust 实现 + 全局缓存 + 硬链接,冷启动快 10 倍,热缓存快 100 倍。

🔒

可重现锁文件

跨平台通用的 uv.lock,精确记录版本+哈希,团队与 CI 完全一致。

🐍

自动管 Python

无需提前装 Python,uv 自动下载对应版本(类似 nvm)。

🧰

一体化工具链

替代 pip / venv / pipx / poetry / pyenv 五个工具,一条命令走天下。

📦

工作区 Monorepo

原生支持多包工作区,子项目共享锁文件与依赖缓存。

🐳

生产部署

官方 Docker 镜像、uv sync --frozen、缓存层优化,CI/CD 极速。

课程目录

从安装到深度集成,10 章覆盖 uv 的每一个核心能力

Chapter 01

认识 uv 与安装

为什么需要 uv、与 pip/poetry/conda 对比、安装方式、shell 补全、环境变量。首次体验从 0 到 1。

入门 安装 对比
Chapter 02

项目初始化与 pyproject.toml

uv init、PEP 621 项目配置详解、[project] / [dependency-groups] 区块、脚本入口、构建后端选择。

uv init pyproject PEP 621
Chapter 03

依赖管理:add / remove / sync

添加/移除依赖、版本约束语法、可选依赖 extras、开发依赖组、git/url/路径依赖、平台标记。

uv add extras dep-groups
Chapter 04

锁文件 uv.lock 深入

uv.lock 结构、跨平台解析机制、哈希校验、--frozen / --locked 区别、冲突解决、手动升级策略。

uv.lock 可重现 SAT 解析
Chapter 05

Python 版本管理

uv python install/list、.python-version 文件、多版本并存、python-build-standalone 原理、Pin 与 Free-Threaded。

uv python pyenv 替代
Chapter 06

虚拟环境与 uv run

uv venv 自动创建、uv run 脚本执行、临时依赖 inline metadata(PEP 723)、shell 激活 vs 免激活。

uv venv uv run PEP 723
Chapter 07

全局工具管理 uv tool

uv tool install(pipx 替代)、isolated tool 环境、uvx 一次性运行、升级与卸载、PATH 接管。

uv tool uvx pipx 替代
Chapter 08

工作区 Workspace

多包 Monorepo 配置、members 与 root、workspace 成员间依赖、共享锁文件、uv build 发布多包。

Workspace Monorepo
Chapter 09

PyTorch / CUDA / 平台约束

多索引源配置、PyTorch CPU/CUDA 变体、fork + marker 策略、私有 PyPI、Tensorflow/JAX 平台依赖。

PyTorch CUDA index
Chapter 10

CI/CD 与 Docker 部署

GitHub Actions 缓存、uv sync --frozen、uv 官方 Docker 镜像、多阶段构建优化、从 pip/poetry 迁移清单。

CI/CD Docker 迁移