UV利器介绍及基本操作

预计阅读时间：20 分钟

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环境中的应用。

1 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环境。

2 UV的安装与常用命令

2.1 安装UV

UV的安装非常简单，支持多种操作系统和安装方式。以下是几种常见的安装方法：

使用官方安装脚本（推荐）

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

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

# 卸载
# 清除 uv 的缓存
uv cache clean

# 删除 uv 管理的 Python 版本
rm -r "$(uv python dir)"

# 删除 uv 安装的工具
rm -r "$(uv tool dir)"

# 删除uv二进制文件， 0.5.0及以上版本
rm ~/.local/bin/uv
rm ~/.local/bin/uvx

若安装很慢，建议采用github中的二进制文件： https://github.com/astral-sh/uv/releases

使用包管理器

# macOS (Homebrew)
brew install uv

# 卸载
brew uninstall uv

# linux 
python3.9 -m pip install -U pip
python3.9 -m pip install pipx
python3.9 -m pipx ensurepath

# 环境变量
# source ~/.bashrc

pipx install uv

安装完成后，可以通过以下命令验证安装是否成功：

uv --version

安装正确会得到版本号：

uv 0.8.0 (0b2357294 2025-07-17)

shell自动补全 https://uv.doczh.com/getting-started/installation/#scoop

# zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc

2.2 创建和管理项目

UV提供了一套完整的命令用于创建和管理Python项目：

创建新项目

# 创建一个新的Python项目目录
uv init example
# 运行正确会显示：Initialized project `example` at `/路径/example`

有三个默认文件：README.md、main.py、pyproject.toml

# 创建一个新的Python项目目录
uv init example
# Initialized project `example` at `/路径/example`

# 在当前目录初始化项目
uv init

# 初始化可打包的应用程序
uv init --app --package

# 初始化可导入的库项目
uv init --lib --package

# 指定 Python 版本
uv init --python 3.x

查看目录内容：

cd example
tree -a -L 1

.
├── .git
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

该 main.py 文件包含一个简单的“Hello world”程序。尝试一下uv run main.py 初始化一个新的虚拟环境： uv venv ，正确运行后得到虚拟环境信息

Using CPython 3.13.1
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

直接运行 main.py 也可以创建虚拟环境

uv run main.py

激活虚拟环境。

source .venv/bin/activate

2.3 依赖管理命令

UV 提供了一系列强大的依赖管理命令，以下是最常用的几个：

添加依赖

使用 uv add 命令可以向项目添加依赖。该命令会自动更新 pyproject.toml 文件、锁文件和项目环境：

# 添加单个包
uv add requests

# 指定版本约束
uv add 'requests==2.31.0'

# 添加 Git 依赖
uv add git+https://github.com/psf/requests

# 从 requirements.txt 文件批量添加所有依赖
uv add -r requirements.txt -c constraints.txt

查看依赖

uv tree

删除依赖

使用 uv remove 命令可以删除项目依赖：

# 删除包
uv remove requests

升级依赖

使用 uv lock 命令配合 --upgrade-package 参数可以升级指定包：

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

该命令会尝试将指定包更新到最新的兼容版本，同时保持锁文件中其他依赖不变。

安装项目依赖

当你有一个包含 pyproject.toml 的项目时，可以使用以下命令安装所有依赖：

# 安装项目依赖
uv pip install -e .

# 安装包含开发依赖
uv pip install -e ".[dev]"

同步项目环境

使用 uv sync 命令可以确保项目环境与锁文件保持同步：

# 同步项目环境
uv sync

运行项目命令

uv run 命令可以在项目环境中运行脚本或命令。在每次运行前，UV 会验证锁文件是否与 pyproject.toml 同步，并确保环境与锁文件一致：

# 运行 Python 脚本
uv run main.py

构建项目分发包

uv build 命令可用于构建项目的源码分发包和二进制分发包（wheel）：

# 构建项目
uv build

# 查看构建结果
ls dist/
# 输出示例：
# Successfully built dist/example-0.1.0.tar.gz
# Successfully built dist/example-0.1.0-py3-none-any.whl

这些命令提供了一个完整的项目依赖管理工作流程，从添加依赖、删除依赖、升级依赖到运行项目和构建分发包。UV 的这些命令设计直观且高效，大大简化了 Python 项目的依赖管理。

2.4 使用工具

UV 提供了强大的工具管理功能，可以替代 pipx 等工具来运行和管理 Python 工具。

运行工具（不安装）

uvx 命令可以在不安装工具的情况下直接运行工具：

# 运行带参数的工具
uvx pycowsay "Hello from UV"
  -------------
< Hello from UV >
  -------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

运行 ruff 代码检查工具

# 运行 ruff 代码检查工具
uvx ruff check .
# All checks passed!

uv tool run ruff check .
# All checks passed!

注意：uvx 是 uv tool run 的便捷别名。使用 uvx 运行的工具会在临时的隔离环境中安装和运行。

指定工具版本

可以使用 @ 语法指定工具的版本：

# 运行特定版本的工具
uvx ruff@0.1.5 check .

# 运行最新版本的工具
uvx ruff@latest check .

也可以使用 --from 选项指定更复杂的版本约束：

# 指定版本范围
uvx --from 'ruff>0.2.0,<0.3.0' ruff check .

安装工具

全局工具安装：如果经常使用某个工具，可以将其安装到持久环境中，并添加到 PATH 中：

# 安装 ruff 工具
uv tool install ruff

# 安装特定版本的工具
uv tool install 'ruff>=0.3.0'

# 从 Git 仓库安装工具
uv tool install git+https://github.com/astral-sh/ruff

安装工具后，可以直接在命令行中运行该工具，无需通过 UV 调用：

# 直接运行已安装的工具
ruff --version

注意：与 uv pip install 不同，安装工具不会在当前环境中提供其模块。这种隔离对于减少工具、脚本和项目之间的依赖冲突非常重要。

升级工具

使用 uv tool upgrade 命令可以升级已安装的工具：

# 升级特定工具
uv tool upgrade ruff

# 升级所有工具
uv tool upgrade --all

工具升级会尊重安装工具时提供的版本约束。例如，如果使用 uv tool install ruff >=0.3,<0.4 安装了 Ruff，然后运行 uv tool upgrade ruff，则将升级 Ruff 到 >=0.3,<0.4 范围内的最新版本。

使用插件和额外依赖

可以使用 --with 选项添加额外的依赖或插件：

# 运行带插件的工具
uvx --with mkdocs-material mkdocs serve

# 安装带插件的工具
uv tool install mkdocs --with mkdocs-material

使用 --from 选项可以运行带有额外功能的工具：

# 使用额外功能
uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report

这些命令使 UV 成为一个强大的 Python 工具管理器，可以替代 pipx 和其他类似工具，并且提供了更高的性能和更多的功能。

2.5 版本与发布

# 查看当前项目版本
uv version

# 版本升级
## 主版本号 +1 （1.0.0 -> 2.0.0）
uv --bump major

## 次版本号 +1 （1.0.0 -> 1.1.0）
uv --bump minor

## 升级为alpha 测试版本
uv --bump alpha

# 构建项目分发包
uv build

# 发布到 PyPi 或私有仓库
uv publish

# 转为稳定版本
uv --bump stable

3 内部原理

UV 的出色性能不仅仅是因为它使用 Rust 语言开发，更在于其内部实现了多种高效的算法和优化策略。下面我们将揭开 UV 的核心技术原理。

3.1 依赖解析器

UV 使用基于 PubGrub 算法的依赖解析器，这是一种增量版本求解器。与传统的 SAT 求解器不同，UV 的解析器具有以下特点：

增量解析：从一个部分解决方案开始，逐步选择包版本，而不是尝试所有可能的组合。
智能优先级：包的选择基于优先级系统，URL 包优先级最高，然后是精确版本说明符，再然后是宽松说明符。
版本偏好：优先使用锁文件和当前环境中的版本，以及最高版本（除非指定其他解析策略）。
预取优化：在后台预取包的元数据，显著提高性能。
智能回溯：当检测到冲突时，解析器会进行回溯，并记录不兼容项，以避免重复尝试无效组合。
有意义的错误报告：当解析失败时，提供清晰的错误跟踪，指出冲突的具体包和版本。

3.2 分叉解析

UV 采用了分叉解析器策略，可以处理不同环境下的矛盾需求：

条件依赖：当包有多个带有不同标记的要求时（如基于 Python 版本或操作系统的条件），解析会被分割。
智能合并：具有相同包的分叉会合并，以保持分叉数量较少。
锁文件稳定性：锁文件中会记录分叉信息，确保解析稳定性。

3.3 Python 版本兼容性

UV 严格处理 Python 版本兼容性，确保所有依赖项都能在指定的 Python 版本上正确安装：

最低版本传播：如果项目要求 Python >= 3.9，那么声明了 Python >= 3.10 的包版本会被拒绝。
版本下限尊重：为了简化和向前兼容，只会尊重 requires-python 中的下限。

3.4 性能优化

UV 的高性能来自于多方面的优化：

Rust 实现：使用 Rust 语言开发，具有出色的性能和内存安全性。
并行下载：并行处理包下载和元数据获取。
智能缓存：全局缓存机制避免重复下载和安装相同的包。
最小化磁盘操作：优化的文件操作和磁盘访问模式。
增量处理：在解析和安装过程中采用增量方法，避免不必要的全量重建。

这些内部原理使 UV 能够在保持兼容性的同时，实现比传统工具快 10-100 倍的性能。对于大型项目和复杂依赖关系，这些优化尤为重要。

4 速查表

下面是 UV 工作流程中的常见操作速查表，帮助您快速查找和使用 UV 的各种命令。

4.1 环境管理

操作	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`
### 4.2 包管理

操作	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`
### 4.3 项目管理

操作	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`

4.4 工具管理

操作	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`
### 4.5 国内镜像源
在 `pyproject.toml` 中添加国内镜像源。

[project]
name = "project-name"
version = "0.1.0"
description = "describe project"
readme = "README.md"
requires-python = ">=3.12"

authors = [
    {name = "xiangyu.yu", email = "xiangyu.yu@unidt.com"}
]

dependencies = [
    "fastapi==0.116.1",
    "ftfy>=6.3.1",
    "zh-core-web-sm",
]

[[tool.uv.index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true

[tool.uv.sources]
zh-core-web-sm = { path = "wheel/zh_core_web_sm-3.8.0-py3-none-any.whl" }
pymupdf = { path = "wheel/pymupdf-1.25.1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", marker = "sys_platform == 'linux'" }

5 多版本Python

无需要 pyenv, uv 内置版本管理

# 安装python
uv python install 3.13

# 自动下载并安装指定版本
uv python list

# 升级现有版本
uv python upgrade

# 以指定版本运行
uv run --python 3.11 python app.py

# 锁定项目版本
uv python pin 3.11

若安装缓慢，建议换源

echo 'export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"'>> ~/.bashrc

# 立即生效
source ~/.bashrc

6 脚本依赖管理

单文件脚本也能享受依赖管理

# 创建带依赖元数据的脚本
uv init --script myscript.py

# 指定脚本使用的 Python 版本
uv init --script myscript.py --python 3.x

# 自动安装依赖并运行
uv run myscript.py

# 临时添加额外依赖运行
uv run myscript.py --with click

# 添加脚本依赖
uv add click --script myscript.py

macOS

在 macOS 环境中安装 uv 模块。

pipx install uv
# 查看版本
pipx list | grep uv

 $ pipx list | grep uv
   package uv 0.8.4, installed using Python 3.13.5
    - uv
    - uvx

安装 yt-dlp 工具。

uvx tool install yt-dlp

全局配置镜像源

mkdir -p ~/.uv
touch ~/.uv/uv.toml

# 添加如下内容
[[tool.uv.index]]
url = "https://pypi.mirrors.ustc.edu.cn/simple/"
default = true

安装 podman-compose 软件，其命令如下所示。

pipx install podman-compose

启动服务

pipx run jupyter-lab

本文由 admin 原创，转载请注明出处。若存在侵权请联系删除。