sitJac's Blog
0%

UV 使用手册

Posted on In
  • uv 试图用一个工具统一解决 Python 安装、虚拟环境、依赖管理、脚本运行和 CLI 工具安装等问题。
  • 它可以理解成 python、venv、pip、pip-tools、pipx 等能力的组合体，而且速度很快。
  • 本文结合实际工作使用，系统整理 uv 的常见工作流，适合拿来作为日常查询手册。

安装 uv

Linux / macOS 下可以直接使用官方安装脚本：

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

或者：

1
wget -qO- https://astral.sh/uv/install.sh | sh

安装完成后，重开终端，确认版本：

1
uv --version

如果命令找不到，一般是因为 uv 的安装目录还没有加入 PATH。

uv 能做什么

相比传统的 python + venv + pip + pipx 组合，uv 主要覆盖下面几类能力：

  1. 安装和管理不同版本的 Python。
  2. 创建和切换项目虚拟环境。
  3. 基于 pyproject.toml 管理项目依赖。
  4. 生成和同步锁文件。
  5. 在项目环境中直接运行脚本、测试和工具。
  6. 全局安装常用 Python CLI 工具。
  7. 兼容一部分传统 requirements.txt 工作流。

如果你是第一次接触 uv，可以先记住一句话：

推荐优先使用 pyproject.toml 的项目流派，uv pip 只在兼容老项目时再用。

Python 版本管理

查看可用 Python

1
uv python list

这个命令会列出 uv 可管理的 Python 版本，适合查看有哪些解释器可以安装。

安装指定 Python

1
uv python install 3.11

安装后，uv 会把对应解释器缓存下来，后面创建虚拟环境时可以直接复用。

查找某个 Python

1
uv python find 3.11

这个命令可以帮助你确认当前系统里 uv 实际找到的 3.11 解释器路径。

给项目固定 Python 版本

1
uv python pin 3.11

执行后通常会在项目目录下生成 .python-version，方便团队成员或工具统一解释器版本。

虚拟环境管理

创建虚拟环境

比如创建一个 Python 3.9 的虚拟环境：

1
2
uv venv --python 3.9 .venv
source .venv/bin/activate

如果不写最后的 .venv，uv 默认也会在当前目录创建 .venv。

另一个常见例子是创建 3.11 环境：

1
uv venv --python 3.11

删除虚拟环境

先退出当前环境：

1
deactivate

然后删除目录：

1
rm -rf .venv

查看项目实际使用的 Python

1
uv run python

它会直接在项目环境里启动 Python，你也可以顺手执行：

1
uv run python --version

临时指定某个 Python 运行命令

1
uv run -p 3.14 python

这个用法适合临时测试不同 Python 版本下的兼容性，而不一定要手动切换当前虚拟环境。

初始化项目

推荐使用 pyproject.toml 来管理项目。

创建项目配置

1
uv init -p 3.9

执行后会初始化当前项目，并生成 pyproject.toml 等基础文件。

一个典型工作流如下：

1
2
3
4
mkdir myproj && cd myproj
uv init -p 3.9
uv venv --python 3.9
source .venv/bin/activate

其中：

  • uv init 负责初始化项目元信息。
  • uv venv 负责准备运行环境。
  • 后续依赖安装建议都通过 uv add 完成。

项目依赖管理

这部分是 uv 最常用的能力。

添加外部依赖

1
uv add requests

指定版本号：

1
uv add onnx==1.4.0 --frozen

这里的 --frozen 一般表示要求锁文件保持一致，不允许随意重新解析整个依赖图，适合想严格控制环境时使用。

添加开发依赖

1
uv add --dev pytest ruff pre-commit

这样这些包会被归类到开发依赖中，而不是生产依赖。

删除依赖

1
2
uv remove requests
uv remove onnx

删除时，uv 会同步更新 pyproject.toml 和相关锁文件。

添加本地 whl 包

如果你手头有一个本地 wheel 文件，也可以直接加到项目里：

1
uv add /home/xiejunjie/Work/Code/mtk_model_trace/3rd_party/offline_tool/mtk_converter-7.16.0+release-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.whl

这种方式特别适合：

  • 公司内部私有包没有上传到公网仓库。
  • 本地要验证一个尚未发布的新版本包。
  • 需要绑定一个明确的 wheel 构建产物。

同步依赖

1
uv sync

当你拉取了别人的代码，或者 pyproject.toml / 锁文件发生变化时，用 uv sync 可以把当前虚拟环境同步到项目声明的状态。

生成锁文件

1
uv lock

锁文件的作用是固定完整依赖图，保证不同机器上安装出的依赖尽量一致。

查看依赖树

1
uv tree

当项目依赖越来越多时，这个命令非常适合排查“某个包到底是谁带进来的”。

在项目环境中运行命令

uv 很适合用来直接运行项目命令，而不用总是手动激活环境。

运行 Python 脚本

1
uv run python3 -c 'import mtk_converter; print(mtk_converter.__version__)'

这个例子可以快速验证刚刚添加的本地 wheel 包是否可用。

查看项目环境中的 Python 版本

1
uv run python --version

运行测试

1
uv run pytest

运行代码检查

1
uv run ruff check .

这一类命令的优点是：

  • 不要求你先 source .venv/bin/activate
  • 命令更适合写进 README、CI 或 shell 脚本
  • 能明确保证是在项目自己的环境中运行

兼容传统 requirements.txt 工作流

有些老项目还没有迁移到 pyproject.toml，这时可以使用 uv pip 子命令。

从 requirements.txt 安装

1
uv pip install -r requirements.txt

导出当前依赖

1
uv pip freeze

不过要注意：

如果是新项目，还是更推荐直接使用 uv add / uv remove / uv lock / uv sync 这一套工作流。

管理全局 CLI 工具

除了项目依赖，uv 还可以像 pipx 一样安装全局命令行工具。

安装工具

1
2
3
4
uv tool install --python 3.11 pre-commit
uv tool install --python 3.11 ruff
uv tool install --python 3.11 black
uv tool install --python 3.11 huggingface-hub

查看已安装工具

1
uv tool list

卸载工具

1
uv tool uninstall pre-commit

查看全局 tool 目录

1
uv tool dir

确认工具命令位置

1
which pre-commit

如果 which 能找到对应命令，说明它已经在 shell 的搜索路径中可用了。

一次性运行工具

有些工具你只想临时用一下，不想全局安装，也不想写进项目依赖，这时可以使用 uvx。

1
2
uvx pre-commit --version
uvx ruff check .

可以把 uvx 理解成“临时执行一个 Python CLI 工具”的入口，类似 npx 的使用体验。

它适合：

  • 临时试用一个工具。
  • 在 CI 或脚本里一次性调用某个命令。
  • 不希望污染全局工具列表。

一套推荐的日常工作流

如果你是从零开始一个 Python 小项目，可以参考下面这套流程：

1. 安装 uv 和 Python

1
2
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.11

2. 初始化项目

1
2
3
4
mkdir demo && cd demo
uv init -p 3.11
uv python pin 3.11
uv venv --python 3.11

3. 添加依赖

1
2
uv add requests
uv add --dev pytest ruff pre-commit

4. 运行命令

1
2
3
uv run python --version
uv run pytest
uv run ruff check .

5. 提交前同步和锁定

1
2
uv lock
uv sync

这样一个项目的 Python 版本、依赖声明、开发工具和运行命令基本就都统一了。

常见命令速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
# 安装 / 查看 Python
uv python list
uv python install 3.11
uv python find 3.11
uv python pin 3.11

# 创建虚拟环境
uv venv --python 3.11
uv venv --python 3.9 .venv
source .venv/bin/activate

# 删除虚拟环境
deactivate
rm -rf .venv

# 初始化项目
uv init -p 3.9

# 项目依赖管理
uv add requests
uv add onnx==1.4.0 --frozen
uv add --dev pytest ruff pre-commit
uv add /path/to/pkg.whl
uv remove requests
uv sync
uv lock
uv tree

# 在项目环境中运行
uv run python --version
uv run pytest
uv run ruff check .
uv run -p 3.14 python
uv run python3 -c 'import mtk_converter; print(mtk_converter.__version__)'

# 兼容旧式 pip 工作流
uv pip install -r requirements.txt
uv pip freeze

# 全局工具管理
uv tool install --python 3.11 pre-commit
uv tool install --python 3.11 ruff
uv tool install --python 3.11 black
uv tool list
uv tool uninstall pre-commit
uv tool dir
which pre-commit

# 临时运行工具
uvx pre-commit --version
uvx ruff check .

什么时候该用哪一套命令

可以简单这样区分：

  • 想管理项目依赖：用 uv add / uv remove / uv lock / uv sync
  • 想兼容旧项目：用 uv pip ...
  • 想跑项目里的命令：用 uv run ...
  • 想装全局 CLI：用 uv tool install ...
  • 想临时执行 CLI：用 uvx ...
  • 想管理解释器版本：用 uv python ...
  • 想创建隔离环境：用 uv venv ...

参考