本文最后更新于:2025年11月6日 凌晨
uv 是由 Astral 公司开发的一款 Rust 编写的 Python 包管理器和环境管理器,它的主要目标是提供比现有工具快 10-100 倍的性能,同时保持简单直观的用户体验。本文介绍相关内容。
简介
UV 是一个由 Astral 公司用 Rust 开发的高性能 Python 包管理工具,旨在提供比传统 pip 更快的包安装和依赖管理体验。
An extremely fast Python package and project manager, written in Rust.
Python 生态系统中的包管理一直是开发者关注的焦点。从最初的 pip 到后来的 Poetry、PDM 等工具,每一次演进都试图解决前代工具的痛点。而今天我们要介绍的 UV,作为由 Ruff 团队(Astral)开发的下一代 Python 包管理工具,正以其惊人的速度和创新的设计理念,重新定义 Python 包管理的标准。
什么是UV?
UV 是一个极速的 Python 包管理器和解析器,由 Rust 编写,专注于提供卓越的性能和用户体验。其名称 “UV” 源自 “μv”(微伏),暗示着其轻量级和高效的特性。作为 pip 的直接替代品,UV 提供了兼容的命令行接口,同时在速度上实现了数量级的提升。
UV的核心优势
与传统的 Python 包管理工具相比,UV 具有以下显著优势:
- 🚀 一体化工具:一个工具替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等多种工具
- ⚡️ 极致速度:比 pip 快 10-100 倍
- 🗂️ 全面项目管理:提供通用锁文件的综合项目管理功能
- ❇️ 脚本运行:支持带有内联依赖元数据的脚本运行
- 🐍 Python版本管理:安装和管理不同的 Python 版本
- 🛠️ 工具安装:运行和安装以 Python 包形式发布的工具
- 🔩 兼容pip接口:提供熟悉的命令行界面,同时大幅提升性能
- 🏢 工作区支持:支持 Cargo 风格的工作区,适用于大规模项目
- 💾 高效磁盘空间利用:通过全局缓存实现依赖去重
- ⏬ 简易安装:无需 Rust 或 Python 环境,可通过 curl 或 pip 直接安装
- 🖥️ 多平台支持:支持 macOS、Linux 和 Windows 系统
随着Python项目规模和复杂度的增长,传统工具在性能和用户体验方面的局限性日益凸显。UV 的出现,为开发者提供了一个更快、更可靠的选择,特别适合大型项目和CI/CD环境中的应用。
UV和其他工具对比
在Python生态系统中,包管理和环境管理工具众多,主要包括pip+virtualenv、Poetry、Conda等。在决定是否采用UV之前,了解它与现有工具的区别和优势非常重要。
UV vs. pip+virtualenv
pip和virtualenv是Python包管理和虚拟环境创建的传统工具组合。UV相比它们具有以下优势:
- 速度:UV的Rust实现使其比pip快10-100倍,特别是在大型项目中
- 集成环境管理:UV将包管理和环境管理集成在一个工具中,简化了工作流程
- 内存使用:UV在包安装和依赖解析过程中使用的内存显著减少
- 错误处理:UV提供更清晰的错误信息和更好的依赖冲突解决方案
- 可复现性:UV的锁文件方法确保了跨系统环境的一致性,这是基本requirements.txt文件无法保证的
UV vs. Conda
Conda是一个完整的包管理解决方案,特别适合科学计算环境。UV与Conda相比:
- 速度:UV的包安装和依赖解析速度远快于Conda的有时缓慢的性能
- 资源占用:UV具有更小的资源占用,意味着更少的内存使用和更快的启动时间
- 集成性:UV与现有Python打包标准和工具无缝集成,更容易与更广泛的Python生态系统协作
- 非Python包:Conda可以管理非Python包和系统级依赖,而UV专注于Python包
UV vs. Poetry
Poetry是另一个现代Python项目管理工具,与UV有许多相似之处:
- 依赖管理:两者都有效处理包依赖和虚拟环境
- 项目结构:两者都提供初始化和构建Python项目的工具
- 锁文件:两者都生成锁文件以确保环境可复现
然而,UV的Rust实现使其在速度和资源使用方面具有显著优势。此外,UV与现有Python包管理工具的兼容性意味着它可以与其他工具(如pip)一起工作,提供了Poetry更固执己见的方法有时缺乏的灵活性。
功能对比表
| 功能特性 | UV | pip+virtualenv | Conda | Poetry |
|---|---|---|---|---|
| 实现语言 | Rust | Python | Python | Python |
| 速度 | 比pip快10-100倍 | 基准线 | 慢于pip | 快于pip |
| 内存使用 | 非常高效 | 较高 | 高 | 中等 |
| 环境管理 | 内置 | 需要单独工具 | 内置 | 内置 |
| 依赖解析 | 快速、现代解析器 | 基础 | 全面 | 现代解析器 |
| 非Python包支持 | 否 | 否 | 是 | 否 |
| 锁文件 | 是 | 否(基本requirements.txt) | 是 | 是 |
| 项目结构化 | 是 | 否 | 否 | 是 |
| 包发布 | 是 | 是(需要twine) | 是 | 是 |
| 兼容性 | 与现有pip生态系统兼容 | 标准Python工具 | 自有生态系统 | 更固执己见的方法 |
| 错误处理 | 清晰的错误信息 | 基本 | 良好 | 良好 |
| 资源占用 | 最小 | 中等 | 重 | 中等 |
| 科学计算焦点 | 否 | 否 | 是 | 否 |
| 跨平台一致性 | 是 | 有限 | 优秀 | 良好 |
总的来说,UV结合了现有工具的最佳特性,同时通过其Rust实现提供了显著的性能优势。对于寻求更快、更可靠的Python包管理解决方案的开发者来说,UV是一个极具吸引力的选择,特别是对于大型项目或CI/CD环境。
UV的安装与常用命令
安装UV
UV的安装非常简单,支持多种操作系统和安装方式。以下是几种常见的安装方法:
使用官方安装脚本(推荐)
1 | |
1 | |
1 | |
1 | |
如果使用单独的安装器, uv 可以更新自己:
1 | |
安装完成后,可以通过以下命令验证安装是否成功:
1 | |
安装正确会得到版本号:
1 | |
管理 Python 版本
uv 可以轻松管理多个 Python 版本,无需额外安装 pyenv 等工具。
查看可用的 Python 版本:
1 | |
输出结果类似如下:
1 | |
安装特定版本的 Python:
1 | |
设置全局默认 Python 版本:
1 | |
创建和管理项目
UV提供了一套完整的命令用于创建和管理Python项目:
创建新项目
1 | |
有三个默认文件:README.md、main.py、pyproject.toml
查看目录内容:
1 | |
介绍uv工具主要使用的两个文件:
pyproject.toml:定义项目的主要依赖,包括项目名称、版本、描述、支持的Python版本等信息uv.lock:记录项目的所有依赖,包括依赖的依赖,且跨平台,确保在不同环境下安装的一致性。这个文件由uv自动管理,不要手动编辑.
通过init创建项目之后,uv工具贴心地帮助我们生成了一些默认文件。
其中 hello.py 只是一段演示用的代码,
随后我们可以根据实际的项目需要删除这个代码文件,换成自己的实际代码。
1 | |
pyproject.toml中是一些项目信息:
1 | |
注意,uv init 创建项目之后,会自动将项目使用Git来管理。
创建项目之后,我们进入项目根文件夹的第一件事就是同步项目依赖。
1 | |
同步之后,会自动查找或下载合适的 Python 版本,创建并设置项目的虚拟环境,构建完整的依赖列表并写入uv.lock 文件,最后将依赖同步到虚拟环境中。
uv sync同步之后,就可以运行项目的代码了。
运行项目
使用uv管理项目, 我们就使用uv的命令来运行代码,不要像以前那样使用python xxx.py来运行。
该 main.py 文件包含一个简单的“Hello world”程序。尝试一下
1 | |
初始化一个新的虚拟环境:
1 | |
注意:uv工具不会自动下载Python包,因此如果设置
-p时指定系统不存在的Python版本,则会报下面的错:
1 | |
启用环境的命令同Python的标准库venv:
1 | |
依赖管理命令
UV 提供了一系列强大的依赖管理命令,以下是最常用的几个:
添加依赖
使用 uv add 命令可以向项目添加依赖。该命令会自动更新 pyproject.toml 文件、锁文件和项目环境:
1 | |
删除依赖
使用 uv remove 命令可以删除项目依赖:
1 | |
升级依赖
使用 uv lock 命令配合 --upgrade-package 参数可以升级指定包:
1 | |
该命令会尝试将指定包更新到最新的兼容版本,同时保持锁文件中其他依赖不变。
同步项目环境
使用 uv sync 命令可以确保项目环境与锁文件保持同步:
1 | |
运行项目命令
uv run 命令可以在项目环境中运行脚本或命令。在每次运行前,UV 会验证锁文件是否与 pyproject.toml 同步,并确保环境与锁文件一致:
1 | |
构建项目分发包
uv build 命令可用于构建项目的源码分发包和二进制分发包(wheel):
1 | |
这些命令提供了一个完整的项目依赖管理工作流程,从添加依赖、删除依赖、升级依赖到运行项目和构建分发包。UV 的这些命令设计直观且高效,大大简化了 Python 项目的依赖管理。
Python 包管理
当需要安装\管理系统环境的 python 包时, uv 提供了类似 pip 的接口
1 | |
uv add VS uv pip install
uv pip install 和 uv add 有重要区别,主要体现在使用场景和工作方式上:
| uv pip install | uv add | |
|---|---|---|
| 用途 | 直接安装包到当前环境, 不记录依赖 | 为项目添加依赖 |
| 工作方式 | 类似于传统的 pip install 不会自动更新 pyproject.toml 或 requirements.txt |
安装包到当前环境, 自动更新 pyproject.toml 中的依赖列表 |
| 适用场景 | 临时安装工具包\ 全局环境安装\ 测试某个包 | 项目开发\ 管理项目依赖 |
对比:
1 | |
- 项目开发:优先使用
uv add来管理依赖 - 临时/工具安装:使用
uv pip install - 生产部署:使用
uv sync根据pyproject.toml安装所有依赖
uv add 是更现代的项目依赖管理方式,符合 Python 打包标准。
区分开发和生产环境
还有一个比较常用的功能是区分开发环境和生产环境的依赖,这个功能在NodeJS和Rust中很常见。
比如,我们想把pandas安装到开发环境中,而把requests安装到生产环境中。
1 | |
安装之后,uv.lock 文件自动添加了各个包及其依赖,这里不再赘述。
从项目的pyproject.toml中可以看出不同环境的包依赖。
1 | |
使用工具
UV 提供了强大的工具管理功能,可以替代 pipx 等工具来运行和管理 Python 工具。
运行工具(不安装)
uvx 命令可以在不安装工具的情况下直接运行工具:
1 | |
运行 ruff 代码检查工具
1 | |
注意:uvx 是 uv tool run 的便捷别名。使用 uvx 运行的工具会在临时的隔离环境中安装和运行。
指定工具版本
可以使用 @ 语法指定工具的版本:
1 | |
也可以使用 --from 选项指定更复杂的版本约束:
1 | |
安装工具
如果经常使用某个工具,可以将其安装到持久环境中,并添加到 PATH 中:
1 | |
安装工具后,可以直接在命令行中运行该工具,无需通过 UV 调用:
1 | |
注意:与 uv pip install 不同,安装工具不会在当前环境中提供其模块。这种隔离对于减少工具、脚本和项目之间的依赖冲突非常重要。
升级工具
使用 uv tool upgrade 命令可以升级已安装的工具:
1 | |
工具升级会尊重安装工具时提供的版本约束。例如,如果使用 uv tool install ruff >=0.3,<0.4 安装了 Ruff,然后运行 uv tool upgrade ruff,则将升级 Ruff 到 >=0.3,<0.4 范围内的最新版本。
使用插件和额外依赖
可以使用 --with 选项添加额外的依赖或插件:
1 | |
使用 --from 选项可以运行带有额外功能的工具:
1 | |
这些命令使 UV 成为一个强大的 Python 工具管理器,可以替代 pipx 和其他类似工具,并且提供了更高的性能和更多的功能。
uv cache-缓存
uv有一个顶级命令uv cache,用于cache的管理。
首先类似pip cache dir ,uv也有一个cache dir命令来查看缓存目录:
1 | |
注意不同系统的默认cache目录是不同的,我的观察是: + Linux: $HOME/.cache/uv + macOS: /Users/<user>/Library/Caches/uv + Windows: C:/Users/<user>/AppData/Local/uv/cache
当然是可以修改cache目录的,指定UV_CACHE_DIR 环境变量就可以。
然后可以用uv cache prune 清除没有用到的缓存数据,比如删除包后,可以用此命令来清除空间。
最后可以彻底地删除cache,命令为uv cache clean,整个cache目录都会被清除掉:
1 | |
环境变量
UV支持一些环境变量的设置,例如缓存目录,index-url等,常见的包括下面这些,这些环境变量可以临时使用,不过建议时加入到你的shell到配置文件,就不用每次都敲一遍。可以复制下面的代码到.bashrc中然后修改对应的变量
1 | |
Docker
UV 提供了多種 Docker 映像,支持在容器化環境中使用。這對於 CI/CD 流程和確保構建環境一致性特別有用。
可以使用預安裝 UV 的映像:
1 | |
或者將 UV 二進制文件複製到自己的映像中:
1 | |
内部原理
UV 的出色性能不仅仅是因为它使用 Rust 语言开发,更在于其内部实现了多种高效的算法和优化策略。下面我们将揭开 UV 的核心技术原理。
依赖解析器
UV 使用基于 PubGrub 算法的依赖解析器,这是一种增量版本求解器。与传统的 SAT 求解器不同,UV 的解析器具有以下特点:
- 增量解析:从一个部分解决方案开始,逐步选择包版本,而不是尝试所有可能的组合。
- 智能优先级:包的选择基于优先级系统,URL 包优先级最高,然后是精确版本说明符,再然后是宽松说明符。
- 版本偏好:优先使用锁文件和当前环境中的版本,以及最高版本(除非指定其他解析策略)。
- 预取优化:在后台预取包的元数据,显著提高性能。
- 智能回溯:当检测到冲突时,解析器会进行回溯,并记录不兼容项,以避免重复尝试无效组合。
- 有意义的错误报告:当解析失败时,提供清晰的错误跟踪,指出冲突的具体包和版本。
分叉解析
UV 采用了分叉解析器策略,可以处理不同环境下的矛盾需求:
- 条件依赖:当包有多个带有不同标记的要求时(如基于 Python 版本或操作系统的条件),解析会被分割。
- 智能合并:具有相同包的分叉会合并,以保持分叉数量较少。
- 锁文件稳定性:锁文件中会记录分叉信息,确保解析稳定性。
Python 版本兼容性
UV 严格处理 Python 版本兼容性,确保所有依赖项都能在指定的 Python 版本上正确安装:
- 最低版本传播:如果项目要求 Python >= 3.9,那么声明了 Python >= 3.10 的包版本会被拒绝。
- 版本下限尊重:为了简化和向前兼容,只会尊重 requires-python 中的下限。
性能优化
UV 的高性能来自于多方面的优化:
- Rust 实现:使用 Rust 语言开发,具有出色的性能和内存安全性。
- 并行下载:并行处理包下载和元数据获取。
- 智能缓存:全局缓存机制避免重复下载和安装相同的包。
- 最小化磁盘操作:优化的文件操作和磁盘访问模式。
- 增量处理:在解析和安装过程中采用增量方法,避免不必要的全量重建。
这些内部原理使 UV 能够在保持兼容性的同时,实现比传统工具快 10-100 倍的性能。对于大型项目和复杂依赖关系,这些优化尤为重要。
速查表
下面是 UV 工作流程中的常见操作速查表,帮助您快速查找和使用 UV 的各种命令。
环境管理
| 操作 | UV 命令 | 传统对应命令 |
|---|---|---|
| 创建虚拟环境 | uv venv |
python -m venv .venv |
| 创建指定 Python 版本的虚拟环境 | uv venv --python=3.10 |
python3.10 -m venv .venv |
| 安装 Python 版本 | uv python install 3.10 |
使用 pyenv 或系统包管理器 |
| 列出可用的 Python 版本 | uv python list |
pyenv versions |
| 激活虚拟环境 | 使用系统激活方式 | source .venv/bin/activate |
包管理
| 操作 | UV 命令 | 传统对应命令 |
|---|---|---|
| 安装单个包 | uv pip install requests |
pip install requests |
| 从 requirements.txt 安装 | uv pip install -r requirements.txt |
pip install -r requirements.txt |
| 安装当前项目 | uv pip install -e . |
pip install -e . |
| 安装开发依赖 | uv pip install -e ".[dev]" |
pip install -e ".[dev]" |
| 生成锁文件 | uv pip compile requirements.in -o requirements.txt |
pip-compile requirements.in -o requirements.txt |
| 升级单个包 | uv pip install --upgrade requests |
pip install --upgrade requests |
项目管理
| 操作 | UV 命令 | 传统对应命令 |
|---|---|---|
| 添加依赖 | uv add requests |
Poetry: poetry add requests |
| 移除依赖 | uv remove requests |
Poetry: poetry remove requests |
| 同步环境 | uv sync |
Poetry: poetry install |
| 升级特定包 | uv sync --upgrade-package requests |
Poetry: poetry update requests |
| 升级所有包 | uv lock --upgrade |
Poetry: poetry update |
| 运行脚本 | uv run python script.py |
Poetry: poetry run python script.py |
| 构建项目 | uv build |
Poetry: poetry build |
工具管理
| 操作 | UV 命令 | 传统对应命令 |
|---|---|---|
| 运行工具(不安装) | uvx ruff check . |
pipx: pipx run ruff check . |
| 运行特定版本工具 | uvx ruff@0.1.5 check . |
pipx: pipx run --spec=ruff==0.1.5 ruff check . |
| 安装工具 | uv tool install ruff |
pipx: pipx install ruff |
| 升级工具 | uv tool upgrade ruff |
pipx: pipx upgrade ruff |
| 升级所有工具 | uv tool upgrade --all |
pipx: pipx upgrade-all |
参考资料
- https://github.com/astral-sh/uv
- https://www.runoob.com/python3/uv-tutorial.html
- https://apframework.com/blog/essay/2025-06-07-Python-UV
- https://www.cnblogs.com/wang_yb/p/18635441
- https://zhuanlan.zhihu.com/p/689976933
- https://www.runoob.com/python3/uv-tutorial.html
文章链接:
https://www.zywvvd.com/notes/coding/python/python-uv-tool/python-uv-tool/
“觉得不错的话,给点打赏吧 ୧(๑•̀⌄•́๑)૭”
微信支付
支付宝支付