下一代的 Python 包管理利器 uv 快速指北

前言与介绍

Python 有一个生态明星公司 Astral Software，在这之前或许很多人已经用过了 ruff 这款 linter，在 GitHub 斩获 15k+ 星的 uv 横空出世三个月，技术圈已涌现上百篇测评。在这之前，我用过诸如 conda 或 poetry 等包管理器，最后还是回归到了 Python 自带的 venv，但在我使用 uv 一个月后，彻底抛弃了 venv。

uv 的官方写到的亮点：

10 - 100 倍快于 pip
全面的项目管理，带有依赖锁文件
支持安装和管理 Python 发行版
提供与 pip 兼容接口
磁盘利用率高，可复用的全局缓存
良好的跨平台支持

uv 整体吸收了 Rust Cargo 的先进包管理经验，使得开发人员可以快速过度到 uv

重新定义 Python 工作流

性能碾压背后的技术革命

Cargo式依赖解析：基于 Rust 实现的 PubGrub 算法，比 pip 快 8-10 倍的依赖解析速度
跨平台缓存机制：首次安装后依赖包全局缓存复用，实测 conda 环境重建速度提升 6 倍
统一工具链：用 uv pip 替代pip，uv venv 管理虚拟环境，uv run 执行脚本

多维度工具对比矩阵

特性	pip	Poetry	Conda	uv
依赖解析速度	1x	0.8x	0.5x	8x
虚拟环境管理	❌	✅	✅	✅
跨平台二进制兼容	❌	❌	✅	✅
项目模板生成	❌	✅	❌	✅
单文件部署	❌	❌	❌	✅

安装、卸载与换源

一行命令安装

uv 的安装非常简单，一行命令即可完成

1
2
3
4
5
# Linux 和 macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

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

卸载

很多文章没有介绍如何卸载，其实非常简单，因为 uv 已经打包成为一个独立的二进制文件，只需移除删除缓存和 uv 本身即可

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 清除缓存
uv cache clean

# 删除本体
# Linux 和 macOS
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

# Windows PowerShell
Remove-Item -Recurse -Force -Path $(uv python dir)
Remove-Item -Recurse -Force -Path $(uv tool dir)

更换 PyPI 源

如果不做任何配置，uv 默认会使用 PyPI 官方源，如果你需要使用国内源，可以使用下面几种办法来更换源（默认都以清华源为例）。

uv 的配置文件分为项目级、用户级和系统级，如果你只想将某个项目的源配置为国内镜像，那么只需要在创建项目后把下面的内容添加到项目目录下的 pyproject.toml

1
2
3
[[tool.uv.index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
default = true

如果想对之后的所有项目都生效，则需要配置全局配置，创建一个全局的配置文件 ~/.config/uv/uv.toml 并将以下内容写入

1
2
3
[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
default = true

项目实战

Python 版本管理

默认情况下，uv 会使用系统中内置的 Python 版本作为项目的 Python 解释器，如果你需要使用特定的 Python 版本，可以使用 uv python 命令来管理 Python 的版本，下面是 uv 提供的一系列命令

命令	用途（中文）
`uv python install`	安装指定版本的 Python
`uv python list`	查看可用的 Python 版本
`uv python find`	查找已安装的 Python 版本
`uv python pin`	将当前项目固定使用特定的 Python 版本
`uv python uninstall`	卸载某个 Python 版本

从零到生产：快速依赖管理

如果你主力管理依赖还是用的 pip，那么只需要在 pip 前面加上 uv 就可以了，uv pip 是一个兼容命令

1
2
3
4
# 创建项目并初始化虚拟环境
mkdir hello-uv
uv venv .venv
uv pip install -r requirements.txt

如果用于开发项目，那么下面是 uv 的最佳实践

创建并初始化项目

1
uv init hello-uv && cd hello-world

管理依赖是我使用 uv 的主要目的，使用 uv 添加依赖非常简单，和 pnpm 和 cargo 差不多，使用 add 来添加依赖

1
uv add requests

指定依赖的版本

1
uv add 'requests==2.32.2'

安装依赖的速度非常快，同时项目目录下还自动生成了 uv.lock 文件用于锁住依赖

使用 uv lock 以及 --upgrade-package 标志升级软件包

1
uv lock --upgrade-package requests

使用 remove 命令删除依赖

1
uv remove requests

如果是使用其他人的项目，将代码克隆下来后，只需要简单的使用 sync 来安装所有依赖

1
uv sync

依赖树可视化

1
2
3
4
5
# 查看依赖树
uv tree

# 查看最多 2 级的依赖，防止依赖树过大
uv tree --depth 2

将会输出

1
2
3
4
5
6
7
Resolved 6 packages in 0.38ms
hello-uv v0.1.0
└── requests v2.32.3
    ├── certifi v2025.4.26
    ├── charset-normalizer v3.4.2
    ├── idna v3.10
    └── urllib3 v2.4.0

在项目根目录创建一个 main.py，然后使用 run 命令启动项目

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# main.py

import requests

def main():
    response = requests.get('https://example.com')
    print(response.status_code)

if __name__ == '__main__':
    main()

1
uv run main.py

构建发行版及发布

使用以下命令构建您的包

1
uv build

默认情况下，uv build 将在当前目录中构建项目，并将构建的工件放在 dist/ 子目录中

使用以下命令发布您的软件包

1
uv publish

使用 --token 或 UV_PUBLISH_TOKEN 设置 PyPI 令牌，或者使用 --username 或 UV_PUBLISH_USERNAME 设置用户名，使用 --password 或 UV_PUBLISH_PASSWORD 设置密码。从 GitHub Actions 发布到 PyPI 时，无需设置任何凭据。只需向 PyPI 项目添加受信任的发布者即可。

整理了一份 uv 项目依赖管理常用命令表

命令	作用
`uv init`	创建一个新的 Python 项目
`uv add`	为项目添加依赖项
`uv remove`	从项目中移除依赖项
`uv sync`	同步项目依赖与环境
`uv lock`	为项目依赖创建锁文件（lockfile）
`uv run`	在项目环境中运行命令
`uv tree`	查看项目的依赖树
`uv build`	将项目构建为可分发的归档文件
`uv publish`	将项目发布到包索引（如 PyPI）

何时该拥抱 uv

✅ 推荐场景：

需要同时维护多个 Python 版本项目
CI/CD 流水线中依赖安装耗时严重
开发跨平台桌面应用或工具包

⚠️ 暂缓使用：

深度依赖 conda 特定科学计算包
企业内网无网络缓存环境
必须支持 Python 2.7 的遗留系统