uv 从入门到精通：Python 包管理的终极形态

全文约 8000 字，建议收藏，按章节循序渐进阅读。

前言：为什么你需要认识 uv

先回答一个最直接的问题：我已经用 pip + venv 用得好好的，为什么要换？

来看一组数据：

某 AI 团队实测：CI/CD 流水线从12 分钟缩短至 1 分 15 秒，构建效率提升 89%。

uv 由 Astral 公司（Ruff 的作者）用 Rust 编写，目标是一把梭哈取代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等一众工具。

一句话总结：它快得不像 Python 工具，但干的全是 Python 的活。

第一章：安装——三分钟搞定

1.1 官方推荐安装方式

macOS / Linux：

curl-LsSfhttps://astral.sh/uv/install.sh|sh

或使用 wget：

wget-qO- https://astral.sh/uv/install.sh|sh

Windows（多种方式可选）：

方式一（推荐，最简洁）：使用 Windows 原生包管理器winget（Windows 11 默认自带）：

winget install--id astral-sh.uv

这条命令会自动从微软商店下载安装 uv，安装完成后即可在终端中使用uv命令。升级同样适用此命令。

方式二（PowerShell 脚本）：

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

也可以 pip 安装（但不推荐，因为失去了独立二进制的好处）：

pipinstalluv

1.2 验证安装

uv--version# 输出类似: uv 0.11.x

好的，我已将 Windows 本地配置文件方式补充到1.3 节中，现在该小节同时包含了**环境变量（临时）和全局配置文件（持久）**两种方式。以下是更新后的完整1.3 节内容，您可以直接替换原文章中的对应部分：

1.3 国内镜像源配置（加速必备）

为了提升包下载速度，建议配置国内 PyPI 镜像。uv 支持两种配置方式，按需选用。

方式一：环境变量（当前会话生效）

适合临时测试或单次使用，关闭终端即失效。

Linux/macOS：

exportUV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

可将该行添加到~/.bashrc或~/.zshrc中以持久化，但更推荐下面的配置文件方式。

Windows PowerShell（临时）：

$env:UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"

方式二：全局配置文件（持久生效，推荐）

配置一次，所有uv命令自动生效，无需重复设置。

Windows：
创建或编辑配置文件C:\Users\<你的用户名>\AppData\Roaming\uv\uv.toml（如果目录或文件不存在，请手动创建），写入以下内容：

[[index]] url = "https://pypi.tuna.tsinghua.edu.cn/simple" default = true

保存后，所有 uv 操作都会默认使用清华镜像源。

Linux / macOS：
配置文件位于~/.config/uv/uv.toml，内容与 Windows 完全相同。

提示：配置完成后，可以运行uv debug查看当前生效的索引地址，确认是否配置成功。如果使用winget安装，配置文件路径不受影响，同样有效。

第二章：核心概念——uv 到底能做什么

uv 的功能可以划分为五个层次：

uv 默认强制使用虚拟环境——这不是缺点，是在帮你养成好习惯。

第三章：基础用法——5 个命令原地起飞

对大多数人来说，下面5 个命令覆盖了 90% 的日常使用场景。

3.1 创建虚拟环境

# 在当前目录创建 .venv（默认名称）uv venv# 指定名称uv venv my_env# 指定 Python 版本（自动下载）uv venv--python3.12

uv 创建虚拟环境的速度在0.05 秒级别，比python -m venv快一个数量级。

3.2 安装包（兼容 pip 语法）

# 安装到当前虚拟环境uv pipinstallnumpy pandas# 从 requirements.txt 安装uv pipinstall-rrequirements.txt# 安装到系统 Python（不推荐，但 CI 中可用）uv pipinstallnumpy--system

关键差异：uv 默认只安装在虚拟环境中，想装到系统需要显式加--system。

3.3 运行脚本（自动管理环境）

uv run python main.py

当你执行uv run时，uv 会自动：

1. 检查/创建虚拟环境
2. 同步依赖（如有pyproject.toml和uv.lock）
3. 在环境中执行命令

你不需要手动source activate，这是 uv 和传统工具最大的体验差异。

3.4 查看帮助

uvhelpuv pip--help

3.5 激活虚拟环境（传统方式，可选）

source.venv/bin/activate# Linux/macOS# .venv\Scripts\activate # Windows

但有了uv run，你几乎不需要手动激活。

第四章：项目级管理——像 Cargo 一样管理 Python 项目

这是 uv 最精华的部分。它把 Python 项目管理提升到了Rust 的 Cargo 级别。

4.1 初始化项目

uv init myprojectcdmyproject

生成的文件结构：

myproject/ ├── .gitignore ├── .python-version # 锁定 Python 版本 ├── README.md ├── main.py # 入口文件 └── pyproject.toml # 项目配置 + 依赖声明

4.2 添加依赖

uvaddrequests fastapi

这会自动更新pyproject.toml中的依赖列表。

pyproject.toml示例：

[project] name = "myproject" version = "0.1.0" dependencies = [ "requests>=2.31.0", "fastapi>=0.104.0", ]

4.3 锁定依赖（生成 uv.lock）

uv lock

uv lock会解析所有依赖的精确版本，生成uv.lock文件。

uv.lock不要手动编辑，它是项目的"依赖快照"，确保团队所有成员和生产环境安装完全一致的版本。

4.4 同步环境

uvsync

uv sync会根据uv.lock安装所有依赖到虚拟环境中。

日常开发流程：

uv init projectcdproject uvaddflask sqlalchemy uv run python app.py# 自动 lock + sync + run

4.5 升级依赖

# 升级所有依赖到最新兼容版本uv lock--upgrade# 升级特定包uv lock --upgrade-package requests

4.6 常用命令速查

第五章：Python 版本管理——告别 pyenv

uv 内置了 Python 版本管理功能，可以完全替代 pyenv。

5.1 安装 Python 版本

# 安装最新版本uv pythoninstall# 安装指定版本uv pythoninstall3.12uv pythoninstall3.113.12# 一次性安装多个# 安装 PyPyuv pythoninstallpypy@3.10

5.2 查看可用/已安装版本

uv python list

5.3 自动下载

uv 最智能的地方：你不需要手动安装 Python。当你执行uv venv --python 3.12时，如果系统没有 3.12，uv 会自动下载安装。

5.4 项目级 Python 版本锁定

uv init生成的.python-version文件会锁定项目使用的 Python 版本，团队成员 clone 后uv sync会自动使用正确的版本。

第六章：脚本运行——单文件也能优雅管理依赖

uv 支持PEP 723（内联依赖元数据），你可以在 Python 文件头部声明依赖。

6.1 在脚本中声明依赖

# /// script# requires-python = ">=3.9"# dependencies = [# "pandas>=2.3.3",# ]# ///importpandasaspd data={"City":["Tokyo","Delhi","Shanghai","Sao Paulo"],"Population_Millions":[37.3,32.0,28.5,22.4]}df=pd.DataFrame(data)print(df)

6.2 直接运行

uv run script.py

uv 会自动读取脚本头部的依赖声明，创建临时环境并执行。

6.3 用 uv add 添加脚本依赖

uvadd--scriptscript.py pandas

这会自动在脚本头部插入/更新依赖声明。

适用场景：数据分析脚本、一次性任务、分享给同事的独立脚本——不需要创建完整项目，但依赖需要被管理。

第七章：工具管理——pipx 的完美替代

uv tool和uvx用于管理 Python 命令行工具，每个工具运行在独立的虚拟环境中。

7.1 临时运行（uvx）

# 一次性运行，用完即焚uvx ruff check.uvx black--versionuvx--python3.10ruff# 指定 Python 版本

uvx是uv tool run的别名。

7.2 永久安装

# 安装到 PATH，全局可用uv toolinstallruff uv toolinstallblack# 之后直接使用ruff check.

7.3 管理已安装的工具

uv tool list# 列出已安装的工具uv tool uninstall ruff# 卸载

对比 pipx：uv 的 Rust 实现让工具安装和运行显著更快。

第八章：高级特性

8.1 工作区（Workspace）——多包协同开发

灵感来自 Rust 的 Cargo workspace，适用于一个仓库包含多个关联 Python 包的场景。

# 根目录 pyproject.toml [tool.uv.workspace] members = ["packages/*"]

工作区的特点：

• 每个包有自己的pyproject.toml
• 共享一个uv.lock文件，确保整个工作区依赖一致
• 包之间可以互相引用（editable 安装）

适用场景：核心库 + CLI 工具、微服务集合、大型 monorepo。

8.2 缓存机制

uv 使用激进的全局缓存来避免重复下载和构建依赖。

缓存位置（可配置）：

• Linux:~/.cache/uv
• macOS:~/Library/Caches/uv
• Windows:%LOCALAPPDATA%\uv\cache

清理缓存：

uv cache clean

8.3 构建和发布包

uv 支持将项目打包并发布到 PyPI：

# 构建分发包uv build# 发布到 PyPIuv publish# 或指定 tokenuv publish--tokenpypi-xxxxx

8.4 与现有项目集成

从 requirements.txt 迁移：

# 1. 初始化项目uv init# 2. 从 requirements.txt 添加依赖uvadd$(catrequirements.txt)# 3. 生成锁文件uv lock

从 Poetry 迁移：

1. 将pyproject.toml中的依赖迁移到[project.dependencies]
2. 运行uv lock生成锁文件
3. 更新 CI/CD 使用uv sync替代poetry install

从 Conda 迁移：

# 导出 conda 环境conda list--explicit>conda_env.txt# 提取 Python 包名，用 uv add 逐个添加

第九章：与 pip 的兼容性

uv 被设计为pip 和 pip-tools 工作流的 drop-in 替代品。

9.1 兼容的命令

几乎所有pip命令都可以直接加uv前缀使用：

uv pipinstall<pkg>uv pip uninstall<pkg>uv pip list uv pip freeze uv pip show<pkg>uv pipinstall-rrequirements.txt

9.2 已知差异

9.3 环境变量控制

uv 会检测VIRTUAL_ENV环境变量：

exportVIRTUAL_ENV=/path/to/venv uv pipinstallnumpy# 安装到指定环境

第十章：实战场景速查

场景 1：新项目从零开始

uv init my_apicdmy_api uvaddfastapi uvicorn uvadd--devpytest black# 开发依赖uv run uvicorn main:app--reload

场景 2：克隆团队项目后

gitclone<repo>cd<repo>uvsync# 一键搞定：创建环境 + 安装所有依赖uv run pytest# 直接跑测试

场景 3：跑一个数据分析脚本

# script.py 头部声明了 pandas 依赖uv run script.py# 自动处理环境

场景 4：CI/CD 流水线（追求极致速度）

# GitHub Actions 示例- name: Install uv run:curl-LsSfhttps://astral.sh/uv/install.sh|sh- name: Sync dependencies run: uvsync--frozen# 不更新锁文件，直接用- name: Run tests run: uv run pytest

场景 5：安装全局 CLI 工具

uv toolinstallruff uv toolinstallhttpie

第十一章：常见问题与避坑指南

Q1：uv 和 Poetry 怎么选？

• uv 更快：依赖解析比 Poetry 快8 倍
• uv 更轻：单二进制 ~10MB，Poetry 需要 Python 环境
• Poetry 更成熟：插件生态更丰富，打包发布流程更完善
• 结论：新项目无脑 uv；已有 Poetry 项目可暂不迁移，但新功能开发建议规划迁移

Q2：uv 能替代 conda 吗？

不能完全替代。conda 擅长管理非 Python 依赖（CUDA、MKL、OpenBLAS）。纯 Python 项目用 uv，需要 CUDA 的深度学习项目用 conda + uv 混合使用。

Q3：uv pip install和uv add有什么区别？

• uv pip install：只安装包，不记录到pyproject.toml
• uv add：安装包并写入pyproject.toml依赖列表

日常开发用uv add，临时调试用uv pip install。

Q4：缓存占空间怎么办？

uv cache clean# 清理所有缓存uv cache prune# 只清理未使用的缓存

Q5：–locked、–frozen、–no-sync 的区别：

Q6：winget 安装后 uv 命令找不到怎么办？（Windows 新增）

winget默认将程序安装在%LOCALAPPDATA%\Programs\uv\目录，如果该目录不在 PATH 中，可手动添加到系统环境变量。或重启终端后再次尝试，通常 winget 会自动处理 PATH 注册。

总结：2026 年，你应该用 uv

uv 不是"又一个 Python 工具"，它是Python 工具链的范式转移。从 Rust 实现到强制虚拟环境，从自动依赖解析到内联脚本依赖，uv 在设计上解决了传统工具积累二十年的痛点。

2026 年不用 uv，约等于 2020 年不用黑屏终端。

开始吧（Windows 用户可以直接 winget 安装）：

# macOS / Linuxcurl-LsSfhttps://astral.sh/uv/install.sh|sh# Windows (Windows 11 推荐)wingetinstall--idastral-sh.uv

验证安装：

uv--version

Happy Coding! 🐍⚡