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

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

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

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

来看一组数据：

操作	pip	uv
安装 NumPy + Pandas（无缓存）	~28 秒	~2.3 秒
安装相同依赖（有缓存）	~12 秒	~0.5 秒
依赖解析（复杂项目）	分钟级	毫秒级

某 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：

bash 复制代码

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

或使用 wget：

bash 复制代码

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

Windows（多种方式可选）：

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

powershell 复制代码

winget install --id astral-sh.uv

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

方式二（PowerShell 脚本）：

powershell 复制代码

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

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

bash 复制代码

pip install uv

1.2 验证安装

bash 复制代码

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

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

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

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

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

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

Linux/macOS：

bash 复制代码

export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

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

Windows PowerShell（临时）：

powershell 复制代码

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

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

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

Windows：

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

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 实现方式	替代的传统工具
包管理	`uv pip install`	pip
虚拟环境	`uv venv`	virtualenv/venv
依赖锁定	`uv.lock` 自动生成	pip-tools + requirements.txt
Python 版本管理	`uv python install`	pyenv
命令行工具管理	`uv tool install` / `uvx`	pipx

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

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

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

3.1 创建虚拟环境

bash 复制代码

# 在当前目录创建 .venv（默认名称）
uv venv

# 指定名称
uv venv my_env

# 指定 Python 版本（自动下载）
uv venv --python 3.12

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

3.2 安装包（兼容 pip 语法）

bash 复制代码

# 安装到当前虚拟环境
uv pip install numpy pandas

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 安装到系统 Python（不推荐，但 CI 中可用）
uv pip install numpy --system

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

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

bash 复制代码

uv run python main.py

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

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

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

3.4 查看帮助

bash 复制代码

uv help
uv pip --help

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

bash 复制代码

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

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

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

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

4.1 初始化项目

bash 复制代码

uv init myproject
cd myproject

生成的文件结构：

复制代码

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

4.2 添加依赖

bash 复制代码

uv add requests fastapi

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

pyproject.toml 示例：

toml 复制代码

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

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

bash 复制代码

uv lock

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

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

4.4 同步环境

bash 复制代码

uv sync

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

日常开发流程：

bash 复制代码

uv init project
cd project
uv add flask sqlalchemy
uv run python app.py   # 自动 lock + sync + run

4.5 升级依赖

bash 复制代码

# 升级所有依赖到最新兼容版本
uv lock --upgrade

# 升级特定包
uv lock --upgrade-package requests

4.6 常用命令速查

命令	作用
`uv init`	初始化新项目
`uv add <pkg>`	添加依赖
`uv remove <pkg>`	移除依赖
`uv lock`	生成/更新锁文件
`uv sync`	同步环境到锁文件状态
`uv run <cmd>`	在项目环境中执行命令
`uv tree`	查看依赖树

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

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

5.1 安装 Python 版本

bash 复制代码

# 安装最新版本
uv python install

# 安装指定版本
uv python install 3.12
uv python install 3.11 3.12  # 一次性安装多个

# 安装 PyPy
uv python install pypy@3.10

5.2 查看可用/已安装版本

bash 复制代码

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 在脚本中声明依赖

python 复制代码

# /// script
# requires-python = ">=3.9"
# dependencies = [
#     "pandas>=2.3.3",
# ]
# ///

import pandas as pd

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 直接运行

bash 复制代码

uv run script.py

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

6.3 用 uv add 添加脚本依赖

bash 复制代码

uv add --script script.py pandas

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

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

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

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

7.1 临时运行（uvx）

bash 复制代码

# 一次性运行，用完即焚
uvx ruff check .
uvx black --version
uvx --python 3.10 ruff  # 指定 Python 版本

uvx 是 uv tool run 的别名。

7.2 永久安装

bash 复制代码

# 安装到 PATH，全局可用
uv tool install ruff
uv tool install black

# 之后直接使用
ruff check .

7.3 管理已安装的工具

bash 复制代码

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

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

第八章：高级特性

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

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

toml 复制代码

# 根目录 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

清理缓存：

bash 复制代码

uv cache clean

8.3 构建和发布包

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

bash 复制代码

# 构建分发包
uv build

# 发布到 PyPI
uv publish
# 或指定 token
uv publish --token pypi-xxxxx

8.4 与现有项目集成

从 requirements.txt 迁移：

bash 复制代码

# 1. 初始化项目
uv init

# 2. 从 requirements.txt 添加依赖
uv add $(cat requirements.txt)

# 3. 生成锁文件
uv lock

从 Poetry 迁移：

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

从 Conda 迁移：

bash 复制代码

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

第九章：与 pip 的兼容性

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

9.1 兼容的命令

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

bash 复制代码

uv pip install <pkg>
uv pip uninstall <pkg>
uv pip list
uv pip freeze
uv pip show <pkg>
uv pip install -r requirements.txt

9.2 已知差异

场景	pip	uv
默认安装位置	当前激活的环境	强制虚拟环境（除非加 `--system`）
依赖解析	顺序解析，慢	并行解析，快 10-100 倍
多索引支持	有限	更灵活

9.3 环境变量控制

uv 会检测 VIRTUAL_ENV 环境变量：

bash 复制代码

export VIRTUAL_ENV=/path/to/venv
uv pip install numpy  # 安装到指定环境

第十章：实战场景速查

场景 1：新项目从零开始

bash 复制代码

uv init my_api
cd my_api
uv add fastapi uvicorn
uv add --dev pytest black  # 开发依赖
uv run uvicorn main:app --reload

场景 2：克隆团队项目后

bash 复制代码

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

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

bash 复制代码

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

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

bash 复制代码

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

场景 5：安装全局 CLI 工具

bash 复制代码

uv tool install ruff
uv tool install httpie

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

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：缓存占空间怎么办？

bash 复制代码

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

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

选项	行为
`--locked`	锁文件过期则报错，不自动更新
`--frozen`	使用锁文件但不检查是否过期
`--no-sync`	不检查环境是否同步

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

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

总结：2026 年，你应该用 uv

你的情况	建议
新项目	直接用 uv ，从 `uv init` 开始
在用 venv + pip	渐进迁移：先用 `uv pip` 替代 `pip`，再引入项目级管理
在用 Poetry	保持，但新功能模块可以试用 uv
数据科学（需要 CUDA）	uv + conda 混合使用
CI/CD	必须换 uv，速度提升肉眼可见

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

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

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

bash 复制代码

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (Windows 11 推荐)
winget install --id astral-sh.uv

验证安装：

bash 复制代码

uv --version

Happy Coding! 🐍⚡

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