uv 是一个用 Rust 编写的新一代 Python 包与项目管理工具，旨在以极高的速度和更现代化的方式，统一管理 Python 的依赖、虚拟环境和项目本身。

可以把它看作 pip、pip-tools、virtualenv 甚至 Poetry 的部分功能结合体，但运行速度比它们快很多。

与 pip 和 Poetry 的核心区别

特性	uv	pip	Poetry
核心定位	一体化的项目管理器	包安装器	依赖管理与打包工具
依赖锁定	uv.lock 文件	无原生支持，依赖 pip-tools	poetry.lock 文件
虚拟环境	自动创建与同步	需手动使用 venv 管理	自动创建与同步
速度	极快 (10-100倍于 pip)	慢	中等
兼容性	兼容 pyproject.toml 与 requirements.txt	主要使用 requirements.txt	主要使用 pyproject.toml
语言	Rust	Python	Python

安装 uv

可以通过官方安装脚本或 pip 安装 uv。

macOS / Linux:

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

Windows (PowerShell):

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

使用 pip (备用):

pip install uv

安装完成后，可以运行 uv --version 来验证是否安装成功。

使用 uv 管理项目：两种工作流

uv 支持两种模式，一种适合快速迁移的“pip 兼容模式”，另一种是更现代、更推荐的项目模式。

路线 A：低改动迁移（保留 requirements.txt）

如果习惯了 pip + requirements.txt 的工作流，这是体验 uv 速度最快的方式。甚至不需要改变现有习惯，只需要把命令从 pip 换成 uv pip。

1. 创建虚拟环境

uv venv

这会在项目目录下创建一个 .venv 虚拟环境。

2. 激活虚拟环境

• macOS/Linux: source .venv/bin/activate

• Windows: .venv\Scripts\activate

3. 安装依赖（精确同步）

uv pip sync requirements.txt

uv pip sync 会确保虚拟环境与 requirements.txt 中的依赖完全一致，它会安装缺失的包，并移除环境中任何未在文件中列出的包。如果只想像 pip install 一样增量安装，可以使用 uv pip install -r requirements.txt。

路线 B：迁移到项目模式（pyproject.toml 与 uv.lock）

这是更推荐的方式，能利用 uv 的锁定和项目定义能力。

1. 初始化项目
在项目目录中运行，它会生成 pyproject.toml (项目配置) 和 .python-version (Python版本) 等文件。

uv init

2. 添加依赖

uv add requests

uv add 会将 requests 添加到 pyproject.toml 的依赖列表中，并自动更新 uv.lock 锁文件。

3. 同步环境
运行以下命令，uv 会自动创建 .venv 虚拟环境，并根据锁文件安装所有依赖。

uv sync

4. 运行脚本或命令
使用 uv run，无需手动激活虚拟环境，即可在项目的环境中执行命令。

uv run main.py

常用 uv 命令

依赖管理

• uv add <package>: 添加依赖并写入 pyproject.toml 和 uv.lock。

• uv remove <package>: 移除依赖。

• uv lock: 仅生成/更新 uv.lock 锁文件，而不安装包。

• uv tree: 以树形结构查看项目的依赖关系。

环境与运行

• uv venv: 在当前目录创建一个虚拟环境（.venv 文件夹）。

• uv run <script>: 在项目虚拟环境中运行脚本或命令。

• uvx <tool>: 临时下载并运行一个工具（如 uvx ruff check），不污染当前项目环境。

Python 版本管理

• uv python install <version>: 下载并安装指定版本的 Python。

• uv python list: 列出所有可用的 Python 版本。

• uv python pin <version>: 将当前项目固定到指定的 Python 版本。

构建与发布

• uv build: 构建项目的源码包和 wheel 包（dist/ 目录）。

• uv publish: 将构建好的包发布到 PyPI。

UV 其实就是一个工具，用来管理 Python 包和虚拟环境，核心就三件事：

1. 创建虚拟环境（隔离项目环境）

2. 安装/删除包

3. 跑项目代码

以前这些要用 pip、venv、requirements.txt 分开做，UV 一个工具全搞定，而且速度飞快。