Python 包管理器 `uv`：原理简介与使用指南1 uv 简介 uv 是一款由 Charlie Marsh（Rust

1 `uv` 简介

uv 是一款由 Charlie Marsh（Rust 社区知名开发者）使用 Rust 语言编写的高性能 Python 包管理器，旨在解决传统工具（如 pip、venv）在速度和效率上的痛点。它的设计目标是成为 Python 生态中的现代化工具链核心组件，提供更快的依赖解析、安装速度，并与现有工具（如 pip、poetry）兼容。

2 原理与技术特性

高性能设计 uv 通过以下技术实现显著的速度提升：
- Rust 语言的高效性：利用 Rust 的并发和内存安全特性，优化依赖解析和下载过程。
- 并行化处理：并行下载依赖包、并行构建环境，减少等待时间。
- 全局缓存机制：所有下载的包和元数据会被全局缓存，避免重复下载。
- 优化的依赖解析算法：基于现代 SAT 求解器算法，快速解决复杂依赖关系。
兼容性与扩展性
- 兼容 pip 命令和 requirements.txt 格式，可直接替代 pip。
- 支持 poetry 的 pyproject.toml，可加速 poetry 的依赖解析。
- 提供类似 venv 的虚拟环境管理功能，但速度更快。
跨平台支持 支持 Windows、Linux 和 macOS，并能管理多个 Python 解释器版本。

3 安装 `uv`

使用独立按照脚本安装

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

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

通过 PyPI 安装

# With pip.
pip install uv

# Or pipx.
pipx install uv

更新如果是通过独立安装程序安装的，uv 可以更新到最新版本：
```
uv self update
```
验证安装
```
uv --version
```

4 基本使用

4.1 管理 Python 版本

uv 内建了下载、管理和选用 Python 版本的功能，类似于 pyenv。（记得可以通过 UV_PYTHON_INSTALL_DIR 环境变量配置这些 Python 的安装位置）

# 列出已安装和当前使用的版本
uv python list

# 显示所有可供下载的补丁版本
uv python list --all-versions

# 只显示已安装的版本
uv python list --only-installed

# 安装最新的稳定版 (如果尚未安装)
uv python install

# 安装特定版本
uv python install 3.11.5

# 安装 3.10 系列的最新可用版
uv python install 3.10

# 查看python管理的目录,受 UV_PYTHON_INSTALL_DIR 影响
uv python dir

# 固定项目 Python 版本, 会在当前目录创建或更新 .python-version 文件，声明项目应使用的 Python 版本。
# 之后 uv venv, uv run, uv sync 等命令会优先查找并使用这个版本。
uv python pin 3.11

# 卸载 Python 版本 
uv python uninstall 3.10.8

# 卸载 3.11 系列所有已安装版本
uv python uninstall 3.11

4.2 管理虚拟环境

替代 python -m venv，速度更快：

# 默认创建 .venv 目录
uv venv  

# 使用 --prefix 指定环境目录：
uv venv --prefix ./myenv

# 指定 Python 版本
uv venv --python 3.11  

# 指定路径创建虚拟环境
uv venv --python 3.11 /root/.venv

# 创建轻量级虚拟环境（无需复制标准库）：
uv venv --seed

# 清除所有缓存文件
uv clean  

# 激活虚拟环境
source /root/.venv/bin/activate

# 退出虚拟环境
deactivate

4.3 安装依赖包

替代 pip install：

# 安装单个包
uv pip install flask

# 查看包信息
uv pip show fastapi

# 升级已有包
uv pip install --upgrade uvicorn

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

# 查看当前安装的包
uv pip list

# 卸载包
uv pip uninstall requests

# 导出依赖
uv pip freeze > requirements.txt

# 使用 --resolution=highest 优先安装最新版本，减少冲突检查：
uv pip install --resolution=highest pandas

4.4 其他场景介绍

初始化项目，uv 管理项目依赖和环境，支持锁定文件、工作区等功能，类似于 rye 或 poetry :

$ uv init example
Initialized project `example` at `/home/user/example`

$ cd example

$ uv add ruff
Creating virtual environment at: .venv
Resolved 2 packages in 170ms
   Built example @ file:///home/user/example
Prepared 2 packages in 627ms
Installed 2 packages in 1ms
 + example==0.1.0 (from file:///home/user/example)
 + ruff==0.5.0

$ uv run ruff check
All checks passed!

$ uv lock
Resolved 2 packages in 0.33ms

$ uv sync
Resolved 2 packages in 0.70ms
Audited 1 package in 0.02ms

单文件依赖管理

管理单文件脚本的依赖管理，希望不同脚本有各自独立依赖的情况。如下这种方式不需要完整项目结构的包依赖。

会在 /Users/xxx/.cache/uv/environments-v2/example-3c6e19aa362d976d/lib/python3.12/site-packages 类似这样的路径中生成脚本依赖。

如果脚本删除可以使用 uv cache clean 进行依赖的清理

echo 'import requests; print(requests.get("https://astral.sh"))' > example.py

uv add --script example.py requests
Updated `example.py`

# 在隔离的虚拟环境中运行脚本
# 
uv run example.py
Reading inline script metadata from: example.py
Installed 5 packages in 12ms
<Response [200]>

# 清理所有未使用的依赖缓存
uv cache clean

# 如果有具体指向脚本的选项
uv remove --script /path/to/example.py

# 清理所有 UV 缓存
uv cache clean --all

管理依赖

# 向当前项目或环境中添加 Python 包，可以指定版本，自动处理依赖关系
uv add numpy
uv add "requests>=2.28.0"

# 从当前环境中移除已安装的 Python 包，可以同时移除多个包
uv remove numpy
uv remove requests pandas

# 根据依赖文件（如 requirements.txt 或 pyproject.toml）同步环境中的包
# 可以移除未在定义文件中列出的包，确保环境中的包与定义文件一致
uv sync
uv sync -r requirements.txt

# 生成或更新锁文件，锁定项目依赖的确切版本。
uv lock
uv lock -r requirements.txt -o requirements.lock

# 在 UV 管理的环境中运行 Python 脚本或命令。不需要手动激活环境
uv run python script.py
uv run pytest

5 性能对比

操作	`uv` 耗时	`pip` 耗时	提升倍数
创建虚拟环境	0.2s	1.5s	7.5x
安装 `numpy+pandas`	3s	12s	4x
解析大型依赖树	0.5s	5s	10x

6 优势总结

极速体验：安装和依赖解析速度显著提升，适合大型项目。
无缝兼容：支持现有 pip 和 poetry 工作流，迁移成本低。
资源优化：全局缓存节省带宽和磁盘空间。
现代化工具链：为 Python 生态提供 Rust 驱动的未来方案。

通过 uv，Python 开发者可以告别缓慢的依赖管理，拥抱更高效的开发体验。其设计理念和性能优化使其成为未来 Python 工具链的重要候选。

7 附录

docs.astral.sh/uv

Python 包管理器 `uv`：原理简介与使用指南

1 uv 简介