从零读懂 uv

先认识几个基础概念

uv 本身不难，难的是它背后的几个 Python 概念。先把这些词弄懂，后面的内容就会顺很多。

Python 解释器interpreter

真正"运行" .py 文件的那个程序。你输入 python3 main.py 时，python3 就是解释器。

一台电脑上常常同时装着好几个版本的解释器。写作时用的这台 Mac 上就有三个，见下表。

模块与包module / package

模块就是一个 .py 文件；包是一个装着模块的文件夹。import dotenv 就是在找一个叫 dotenv 的模块或包。

日常说"装一个包"，指的是发行包（distribution）：别人打包好、发布出来的代码，比如 python-dotenv。注意：发行包的名字和 import 时用的名字不一定相同，第 7 课会讲原因。

PyPI

Python 官方的公共包仓库，网址是 pypi.org。uv add 默认就是从这里下载包。

依赖dependency

一个项目需要用到的包。分两种：

• 直接依赖：你亲自要求安装的，比如 typesafe-sdk。
• 间接依赖（也叫传递依赖）：依赖的依赖。typesafe-sdk 自己又需要 pydantic、httpx2 等，它们会被自动装上。示例项目只加了 2 个包，实际却装了 14 个，原因就在这里。

虚拟环境virtual environment

项目专属的一个独立文件夹（就是项目里的 .venv），里面装着这个项目需要的所有包，并指向一个特定版本的解释器。

为什么需要它？假设项目 A 需要 pydantic 1.x，项目 B 需要 2.x。如果都装到系统里，二者必然冲突。给每个项目一个自己的虚拟环境，就互不干扰了。

锁文件lockfile

一份记录"每个包（包括间接依赖）的精确版本号"的清单，uv 项目里的 uv.lock 就是。它保证今天、明天、在你或别人的电脑上装出来的东西完全一样。

上表整理自写作时 uv python list --only-installed 的输出。在你的电脑上运行它，就能看到你自己有哪些版本。

最重要的心智模型：三层

理解 uv 最关键的一点：你的依赖信息存在三个地方，各自扮演不同的角色。用"买菜"来类比：

几乎所有 uv 命令都可以归结为"让这三层保持一致"：

• uv add 包名：写进清单 → 更新小票 → 放进冰箱，三层一起更新。
• uv lock：只根据清单重新生成小票。
• uv sync：按小票把冰箱整理成完全一致的状态，缺的补上，多的扔掉。
• uv run：运行前先更新小票、补上冰箱里缺的东西，然后运行。注意，它默认只补不扔。

动手看一看：三层状态模拟器

下面是在一个全新项目里实际执行的 9 个操作，终端输出原样保留。一步步点下去，观察每一层怎么变化：绿色是新增，红色划线是删除。

uv 是什么，替代了什么

uv 是一个用 Rust 编写的 Python 项目管理工具。过去做同样的事要组合好几个工具，uv 把它们合成了一个，而且快很多。

网上的旧教程，在 uv 项目里怎么写

很多教程还是 pip 时代写的。遇到时照这张表翻译即可：

它为什么快

除了 Rust 本身快，uv 还有一个全局缓存：下载过的包都存在 ~/.cache/uv（可用 uv cache dir 查看）。第二个项目再用同一个包时，直接从缓存里克隆过去，几乎不用等，也不会多占磁盘空间。原理见 第 7 课。

一个 uv 项目的结构，逐个文件看

点击文件列表里的文件名，看每个文件是谁创建的、做什么用、能不能手动修改、要不要提交到 git。以示例项目 jev-cli 为例，内容是写作时的真实文件。

对照一下：刚执行完 uv init 时，只有 pyproject.toml、.python-version、.gitignore、README.md 和 .git/。uv.lock 和 .venv/ 要等你第一次执行 uv add、uv sync 或 uv run 时才会出现。.env、.env.example 和 main.py 是项目自己加的，与 uv 无关。

关于 git：提交什么，不提交什么

规则很简单：可以重新生成的，或者含有秘密的，不提交；描述项目本身的，提交。

pyproject.toml：项目的身份证

这是现代 Python 项目的标准配置文件。它不是 uv 独有的，而是由 PEP 621 规范定义的。任何工具看到它，就知道"这是一个 Python 项目，叫什么，需要什么"。

先看懂 TOML 语法

TOML 是一种配置文件格式，只需要知道三条规则：

• 用方括号括起来的 [project] 是一个段落（TOML 里叫"表"），下面的内容都属于它。[tool.uv] 这种带点的写法表示嵌套：tool 表里的 uv 表。
• name = "jev-cli" 是键 = 值，字符串要加双引号。
• [ "a", "b" ] 是列表，可以跨行写，最后一项后面的逗号可有可无。

逐行解读你的文件

版本号的含义：语义化版本

大多数 Python 包的版本号遵循"语义化版本"（SemVer）惯例，三个数字各有含义：

注意两点：一是这只是惯例，不是强制规定，有的包并不严格遵守；二是主版本为 0 时（比如 typesafe-sdk 0.7.1）表示还在早期开发阶段，次版本升级也可能带来不兼容的改动。

版本约束符号怎么读

指定版本的写法：uv add "typesafe-sdk==0.7.1"。命令里的约束要加引号，否则 shell 会把 > 当成重定向符号，结果生成一个名叫 =0.7.1 的文件。

你将来可能看到的其他段落

[dependency-groups]

开发时才用的依赖，比如测试框架 pytest。用 uv add --dev pytest 添加后会出现：

[dependency-groups]
dev = [
    "pytest>=9.1.1",
]

[project.scripts]
[build-system]

把项目做成"可安装的包"时才需要。在 uv 0.12 中，uv init 默认会生成它们。示例项目只是一个脚本，用不到，所以创建后删掉了它们。第 13 课会详细讲它们的作用。

[tool.uv]

uv 自己的设置。[tool.xxx] 是约定俗成的写法：每个工具都可以在 pyproject.toml 里占一个自己的 tool 段，互不干扰，比如 [tool.ruff]、[tool.pytest.ini_options]。

uv.lock 与依赖解析

pyproject.toml 里写的是 typesafe-sdk>=0.7.1，这是一个范围。从范围得到精确版本的过程叫"依赖解析"，uv.lock 就是解析的结果。

为什么需要锁文件

今天满足 >=0.7.1 的最新版是 0.7.1，半年后可能就是 0.9.0。如果只有 pyproject.toml，你今天装的和半年后同事装的就不是同一个版本，间接依赖更是可能全都变了。"在我电脑上能跑"的问题就是这样来的。

uv.lock 把某一时刻解析出来的每一个包的精确版本、下载地址和文件哈希值都记录下来，包括间接依赖。只要有它，任何人在任何时间装出来的环境都一模一样。

uv 怎么从"范围"得到"精确版本"

每个包发布时都会声明自己需要什么。比如 typesafe-sdk 0.7.1 声明了"需要 pydantic ≥ 2.12、需要 Python ≥ 3.10"等。uv 把你的要求和所有包的要求放在一起，找出一组能同时满足的版本，一般尽量选最新的。这个过程叫依赖解析。

什么时候会发生解析？uv add、uv remove、uv lock 一定会；uv sync 和 uv run 在发现 pyproject.toml 改过时也会。解析的结果写进 uv.lock。

还有一条很重要的规则：已经锁定的版本，uv 会尽量保持不变。即使 PyPI 上出了新版本，只要旧版本仍满足约束，再次解析时也不会自动升级。想升级必须明确说出来（第 9 课详细对比）。这正是锁文件的意义：版本只在你要求时才变。

一个真实的"回退"例子

在一个新项目里同时要求 typesafe-sdk 和 pydantic<2。typesafe-sdk 最新版要求 pydantic ≥ 2.12，二者矛盾。uv 没有报错，而是做了这件事：

$ uv add typesafe-sdk "pydantic<2"
Resolved 13 packages in 1.45s
 + pydantic==1.10.26
 + typesafe-sdk==0.6.0          # ← 不是最新的 0.7.1！
 + msgspec==0.21.1              # ← 0.6.0 版才有的依赖
 …

uv 往回找，发现 typesafe-sdk 0.6.0 还支持 pydantic 1，就选了它，并在 pyproject.toml 里写下了 "typesafe-sdk>=0.6.0"。这是正确的解，但很可能不是你想要的。所以养成习惯：uv add 之后扫一眼输出，看版本号是不是你预期的。

如果明确要求 0.7 以上（uv add "typesafe-sdk>=0.7" "pydantic<2"），就无路可退了，uv 会报错。怎么读这类报错，见 第 14 课。

它长什么样

version = 1
revision = 3
requires-python = ">=3.12"

[[package]]                                     # 双方括号 = 列表里的一项，每个包一项
name = "annotated-types"
version = "0.8.0"                                 # 精确版本
source = { registry = "https://pypi.org/simple" }  # 从哪里下载
wheels = [
    { url = "https://files.pythonhosted.org/…whl",
      hash = "sha256:f072f4d8…" },              # 防篡改校验
]

为什么 uv.lock 里的包比 .venv 里多？

示例项目的 .venv 装了 14 个包，uv.lock 里却有 16 个条目。多出来的两个：一个是项目自己（jev-cli）；另一个是 httpx2-jsfetch，示例项目所在的 Mac 上根本没装它。看看 uv.lock 里的这几行：

{ name = "anyio",          marker = "sys_platform != 'emscripten'" },
{ name = "httpx2-jsfetch", marker = "sys_platform == 'emscripten'" },
{ name = "typing-extensions", marker = "python_full_version < '3.13'" },

marker 是条件：httpx2-jsfetch 只在 emscripten 平台（运行在浏览器里的 Python）上才需要。uv.lock 是通用锁文件，它为所有可能的平台和 Python 版本一次性解好，所以会把这些条件依赖也记下来；实际安装时，uv 只装当前平台需要的那部分。

这也是 uv.lock 那么长的原因：比如 pydantic-core 含有编译过的代码，需要为不同系统、不同 Python 版本各准备一个安装包，光它一个就在 uv.lock 里列了六十多个下载地址。

用 uv tree 看依赖关系

想知道谁依赖谁，运行 uv tree。这是示例项目在写作时的输出：

jev-cli v0.1.0
├── python-dotenv v1.2.3                # 直接依赖
└── typesafe-sdk v0.7.1                 # 直接依赖
    ├── httpx2 v2.13.1                  # ↓ 以下都是间接依赖
    │   ├── anyio v4.15.1
    │   │   ├── idna v3.20
    │   │   └── typing-extensions v4.16.0
    │   ├── httpcore2 v2.13.1
    │   │   ├── h11 v0.16.0
    │   │   └── truststore v0.10.4
    │   └── …
    ├── pydantic v2.13.5
    │   ├── annotated-types v0.8.0
    │   ├── pydantic-core v2.46.5
    │   └── …
    ├── tenacity v9.1.4
    └── typing-extensions v4.16.0

常用变体：uv tree --depth 1 只看直接依赖；uv tree --outdated 标出有新版本的包；uv tree --invert --package pydantic 反过来查"谁依赖了 pydantic"。

.venv：项目专属的"冰箱"

.venv 就是这个项目的虚拟环境。它只是一个普通文件夹，没什么神秘的。这一课讲清楚它里面有什么、为什么必须用 uv run，以及它会不会占用很多空间。

.venv/
├── pyvenv.cfg              # 说明这个环境用的是哪个解释器
├── bin/
│   ├── python → …python3.12 # 指向 uv 管理的 Python 3.12（符号链接）
│   ├── activate            # "激活"脚本（用 uv run 就不需要）
│   └── dotenv              # 某些包自带的命令行工具也装在这里
└── lib/python3.12/
    └── site-packages/      # ← 所有装好的包都在这里
        ├── typesafe_sdk/
        ├── dotenv/
        └── …

home = ~/.local/share/uv/python/cpython-3.12-macos-aarch64-none/bin
implementation = CPython
uv = 0.12.3
version_info = 3.12
include-system-site-packages = false   # 与系统里装的包完全隔离
prompt = jev-cli

为什么必须用 uv run，import 才找得到包

Python 执行 import 时，只会在几个固定位置里找：标准库、当前目录，以及正在运行的那个解释器对应的包目录（site-packages）。

• 用 uv run，运行的是 .venv/bin/python，找的就是 .venv/lib/python3.12/site-packages，你用 uv 装的包都在这里。
• 用系统的 python3，找的是系统自己的目录，那里没有这些包，于是报 ModuleNotFoundError。

想确认某个包到底是从哪里导入的，可以直接问它：

$ uv run python -c "import typesafe_sdk; print(typesafe_sdk.__file__)"
项目目录/.venv/lib/python3.12/site-packages/typesafe_sdk/__init__.py

包名和 import 名为什么不一样

uv add 时用的名字，和代码里 import 的名字，经常对不上：

发行包名是作者在 PyPI 上注册的名字，import 名由包里的代码决定，两者没有强制关系。另外，Python 的名字里不能有 -，所以 typesafe-sdk 在代码里就成了 typesafe_sdk。想知道 import 名，最可靠的办法是看包的文档。

每个项目一个 .venv，会不会很占空间？

不会。听起来像是"每个项目都下载一份解释器和所有依赖"，但实际上 uv 让它们共享同一份数据：

解释器符号链接

.venv/bin/python 不是一份真正的 Python，只是一个"快捷方式"：

$ ls -l .venv/bin/python
.venv/bin/python -> ~/.local/share/uv/python/cpython-3.12-macos-aarch64-none/bin/python3.12

不管有多少个项目用 3.12，磁盘上都只有那一份约 72 MB 的解释器。

依赖包写时复制 clone

包第一次被需要时下载进全局缓存 ~/.cache/uv，之后装到任何项目的 .venv，都是从缓存里克隆过去。这是 uv 在 macOS 和 Linux 上的默认方式（Windows 上用硬链接）。

macOS 默认使用 APFS 文件系统。克隆出来的文件和缓存里的原文件共用同一块磁盘空间，只有某个文件被修改时才会真正复制一份。装好的包基本不会被修改，所以十个项目都用 typesafe-sdk，磁盘上实际也只存了一份。

真正会越来越大的是缓存本身：旧版本的包、已删除项目用过的包都还留在里面。清理方法：

$ uv cache dir                # 缓存在哪里（macOS 上默认是 ~/.cache/uv）
$ du -sh ~/.cache/uv          # 占了多少空间
$ uv cache prune              # 只删不再需要的条目，比较安全，推荐
$ uv cache clean              # 全部清空：项目不会坏，只是下次安装要重新下载
$ uv python uninstall 3.13    # 删掉不用的 Python 版本

为什么清空缓存不会弄坏项目？因为克隆出来的文件是独立的，即使原件被删除，.venv 里那一份依然完好。只有在手动把链接模式设成 symlink 时，清空缓存才会弄坏环境，所以不建议改这个设置。

关于 .venv 的三条规则

• 可以随时删除。运行 uv sync 就会按 uv.lock 原样重建。环境出现奇怪问题时，这是最有效的"重启大法"。
• 不提交到 git。它和你的电脑、系统相关，别人拿去也用不了。别人只需要 pyproject.toml 和 uv.lock，就能在自己电脑上重建。
• 不要往里手动装东西。用 pip 装进去的包 uv.lock 里没有记录，下次 uv sync 时会被清掉（模拟器第 7、8 步演示过）。

"激活"虚拟环境是什么？

传统做法是先运行 source .venv/bin/activate。它做的事情很简单：把 .venv/bin 放到 PATH 环境变量的最前面，于是你之后输入的 python 就是 .venv 里那个，终端提示符也会变成 (jev-cli) $。输入 deactivate 恢复原状。

用 uv 的话基本不需要激活，uv run 每次都会自动使用 .venv。下面两种方式效果相同：

# 方式一（推荐）：一步到位
$ uv run main.py

# 方式二：传统方式，先激活再运行
$ source .venv/bin/activate
$ python main.py
$ deactivate

uv run main.py 背后发生了什么

这是你用得最多的命令。它看起来只是"运行一下"，其实每次都会先检查一遍环境，把缺的补上，然后才执行你的代码。

1. 找到项目根目录从当前目录开始往上找 pyproject.toml。找到了，就知道"这是哪个项目"。所以在项目的子目录里运行也没问题。
2. 确定 Python 版本读取 .python-version（示例项目里是 3.12），并确认它满足 requires-python。电脑上没有这个版本就自动下载。
3. 确保 .venv 存在没有就用选定的解释器新建一个；版本不对就重建。
4. 检查 uv.lock 是否过期如果你手改过 pyproject.toml，uv 会先重新锁定，更新 uv.lock。
5. 补齐 .venv把 uv.lock 里有、.venv 里没有的包装上。注意：默认只补不删，.venv 里多出来的包会保留。想要严格一致，用 uv sync 或 uv run --exact。
6. 用 .venv 里的 Python 执行命令相当于运行 .venv/bin/python main.py，所以 import typesafe_sdk 能找到包。

第一次在新项目里运行时，能看到这些步骤的痕迹（新建示例项目的真实输出）：

$ uv run main.py
Using CPython 3.12.13                    # 第 2 步：选定解释器
Creating virtual environment at: .venv   # 第 3 步：新建 .venv
Hello from demo!                         # 第 6 步：你的程序输出

控制它"修不修"：--locked、--frozen、--exact

默认情况下 uv run 会自动修好环境，这在自己电脑上很方便。但有时你希望它别自作主张，比如在自动化部署里，你希望"uv.lock 过期了就报错"，而不是悄悄更新它。

--locked 的真实报错（手改了 pyproject.toml 之后运行，模拟器第 5 步）：

$ uv run --locked main.py
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.

hint: To update the lockfile, run `uv lock`.

uv sync 也支持 --locked 和 --frozen，含义相同。

对比：绕过 uv，直接用系统的 python3

如果在示例项目里直接运行 python3 main.py，用的是 macOS 自带的 3.9.6，它根本不会去 .venv 里找包：

$ python3 main.py
Traceback (most recent call last):
  …
    from dotenv import load_dotenv
ModuleNotFoundError: No module named 'dotenv'

uv run 不只能运行 .py 文件

$ uv run python                         # 打开交互式 Python，可以直接 import 项目依赖来试验
$ uv run pytest                         # 运行 .venv 里装的命令行工具
$ uv run --with rich python             # 临时加上 rich 试一试，不写进项目（见第 9 课）
$ uv run --env-file .env main.py        # 让 uv 替你加载 .env（不需要 python-dotenv）

容易混淆的命令：到底有什么区别

很多命令看起来差不多，执行后的结果却不一样。这一课把最容易搞混的几组放在一起对比。每一组的输出都是写作时实际运行得到的。

① 装包：uv add、uv pip install、手改 pyproject.toml

结论永远用 uv add。另外两种都会让三层暂时或永久地不一致。

手改 pyproject.toml 并不算错，只是改完要记得运行一次 uv sync（或 uv lock），再把 uv.lock 一起提交。第 2 课模拟器的第 4～8 步完整演示了后两种情况。

② 让改动生效：uv lock、uv sync、uv run

结论uv lock 只动小票；uv sync 把冰箱整理得和小票一模一样；uv run 只补不扔，然后运行。

uv sync 和 uv run 都可以加 --locked 或 --frozen，二者经常被搞混。测试方法：在 pyproject.toml 里手动加一行 "six"（不更新 uv.lock），然后分别运行：

$ uv sync --locked
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.
#   → 发现 uv.lock 过期，报错退出，什么都没改

$ uv sync --frozen
Checked 6 packages in 0.81ms
#   → 完全不看 pyproject.toml，照旧的 uv.lock 检查了一遍。six 根本没装！

$ uv sync
Resolved 9 packages in 2ms
Installed 1 package in 1ms
 + six==1.17.0
#   → 先更新 uv.lock，再装上 six

③ 升级：哪些操作真的会升级，哪些不会

结论已锁定的版本只要仍满足约束，就不会自动升级。想升级，要么用 --upgrade-package，要么提高约束的下限。

测试准备：项目依赖 idna，约束是 >=3.6，uv.lock 里锁定的是 3.6，PyPI 上最新版是 3.20。然后逐个尝试：

# 分两步：先改小票，再让冰箱跟上
$ uv lock --upgrade-package idna
Resolved 2 packages in 422ms
Updated idna v3.6 -> v3.20
$ uv run python -c "import idna; print(idna.__version__)"
Uninstalled 1 package in 1ms          # ← uv run 发现 .venv 与 uv.lock 不一致，先换版本
Installed 1 package in 3ms
3.20

# 一步到位
$ uv sync --upgrade-package idna
Resolved 2 packages in 433ms
 - idna==3.6
 + idna==3.20

注意 --upgrade-package 只会在 pyproject.toml 允许的范围内升级，不会修改 pyproject.toml。如果你写的是 <4，它最多升到 3.x；想跨过这个上限，得先改约束。另外，升级后记得运行一遍程序，确认新版本没有带来问题。

④ 删除依赖：uv remove 与手动删除

结论uv remove 一步清理干净；手动删除后，只有 uv sync 才会把包从 .venv 里移除。

uv remove 只能删除直接依赖。想删一个间接依赖（比如 requests 带进来的 urllib3）会报错：

$ uv remove urllib3
error: The dependency `urllib3` could not be found in `project.dependencies`

这很合理：只要 requests 还在，它就需要 urllib3。想去掉 urllib3，只能去掉需要它的那个包。拼错名字，或者要删的包其实在 dev 组里（应该用 uv remove --dev），也会看到同样的报错。

⑤ 普通依赖与开发依赖：uv add 与 uv add --dev

结论程序运行时需要的，用 uv add；只在开发时用的（测试、代码检查），用 uv add --dev。

$ uv sync --no-dev
Resolved 8 packages in 2ms
Uninstalled 5 packages in 22ms
 - iniconfig==2.3.0
 - packaging==26.3
 - pluggy==1.6.0
 - pygments==2.21.0
 - pytest==9.1.1          # pytest 和它的间接依赖都被移除
$ uv sync                 # 不加 --no-dev，又全部装回来
Installed 5 packages in 4ms

⑥ 切换 Python 版本：install、pin 与 requires-python

结论想让项目换一个 Python 版本，用 uv python pin；uv python install 只负责下载，不改变项目。

$ uv python pin 3.13
Updated `.python-version` from `3.12` -> `3.13`
$ uv run python --version
Using CPython 3.13.15
Removed virtual environment at: .venv     # ← 旧的 3.12 环境被删除
Creating virtual environment at: .venv    # ← 用 3.13 重建
Installed 6 packages in 4ms               # ← 按 uv.lock 重新装包
Python 3.13.15

切回去也是同样的过程。由于包都在缓存里，来回切换只需几毫秒。

⑦ 创建环境：uv venv 与 uv sync

结论在 uv 项目里用 uv sync（或者直接 uv run），基本用不到 uv venv。

uv venv 只创建一个空的虚拟环境，不看 pyproject.toml，也不装任何包：

$ uv venv
Using CPython 3.13.15
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
# site-packages 里除了两个内部文件，什么包都没有

uv sync 则会创建环境，并按 uv.lock 装好所有包。uv venv 是给不用 pyproject.toml 的老式工作流准备的（配合 uv pip install）。

⑧ 使用命令行工具：四种方式

结论看"谁需要它、要用多久"：偶尔用一次，用 uvx；自己常用，用 uv tool install；团队都得用，用 uv add --dev；临时试个库，用 uv run --with。

⑨ 新建：三种 uv init

命令手册：每条命令改动了什么

每条命令都写明了"执行后依次发生什么"。右侧标签表示这条命令会写入哪些文件或目录。想看命令之间的区别，回到 第 9 课。

标签说明：pyproject uv.lock .venv .python-version 表示会被修改（颜色与三层模型一致）；只读 表示只查看，不改动任何东西。

$ uv init my-tool --no-package -p 3.12
Initialized project `my-tool` at `…/my-tool`

$ uv add requests
 + certifi==2026.7.22
 + charset-normalizer==3.5.1
 + idna==3.20
 + requests==2.34.2          # 你要的包
 + urllib3==2.8.0            # 其余都是它的间接依赖

$ uv add "requests==2.31.0"   # 指定版本（记得加引号）
$ uv add rich httpx           # 一次添加多个
$ uv add -r requirements.txt  # 从旧的 requirements.txt 批量导入

$ uv add --dev pytest
$ uv remove --dev pytest      # 删除时也要加 --dev

$ uv remove requests
 - idna==3.20
 - requests==2.34.2
 - urllib3==2.8.0

$ uv run main.py
$ uv run --locked main.py     # uv.lock 过期就报错
$ uv run --exact main.py      # 同时删除 .venv 里多余的包
$ uv run --with rich main.py  # 临时多加一个包，不写进项目

$ uv sync
$ uv sync --no-dev                     # 不装（并卸载）开发依赖
$ uv sync --locked                     # uv.lock 过期时报错，不自动更新
$ uv sync --frozen                     # 忽略 pyproject.toml 的改动，只按现有 uv.lock
$ uv sync --inexact                    # 不删除多余的包
$ uv sync --upgrade-package 包名        # 升级一个包并立即装上

$ uv lock --upgrade-package typesafe-sdk   # 只升级这一个包（在约束范围内取最新版）
$ uv lock --upgrade                        # 所有包都升到允许的最新版
$ uv lock --check                          # 只检查 uv.lock 是否过期，不修改

$ uv tree --depth 1                      # 只看直接依赖
$ uv tree --outdated                     # 标出有新版本的包
$ uv tree --invert --package pydantic    # 谁依赖了 pydantic

$ uv export --format requirements-txt > requirements.txt

$ uv python list --only-installed   # 只看已经装好的（第 1 课的表格就来自它）

$ uv python install 3.13
$ uv python uninstall 3.13

$ uv python pin 3.13
Updated `.python-version` from `3.12` -> `3.13`

$ uvx ruff check .           # 检查代码问题
$ uv tool install ruff       # 想长期使用就全局安装，之后直接输入 ruff

$ uv cache dir
$ uv cache prune
$ uv cache clean

$ uv add --help
$ uv help sync
$ uv --version

常见场景：照着做就行

从零开始一个新项目

$ uv init my-tool --no-package   # 1. 创建项目文件夹和基础文件
$ cd my-tool                     # 2. 进入项目
$ uv add requests                # 3. 添加需要的库
$ uv run main.py                 # 4. 编辑 main.py 后运行
$ git add . && git commit -m "init"   # 5. 提交（.venv 会被 .gitignore 自动排除）

拿到别人的 uv 项目（或者换了一台电脑）

$ git clone <仓库地址> && cd <项目>
$ cp .env.example .env           # 如果项目需要密钥，照模板填上自己的
$ uv sync                        # 按 uv.lock 装出一模一样的环境（也可以跳过，直接 uv run）
$ uv run main.py

这就是提交 uv.lock 的意义：对方不需要问你"装的是哪个版本"。

把旧的 pip 项目迁移到 uv

假设旧项目里有 main.py 和 requirements.txt（这个流程实测可用）：

$ cd 旧项目
$ uv init --no-package           # 已有的 main.py 不会被覆盖
$ uv add -r requirements.txt     # 依赖原样写进 pyproject.toml，并生成 uv.lock
$ uv run main.py
# 确认没问题后，可以删掉旧的 venv/ 文件夹和 requirements.txt

requirements.txt 里如果写的是 == 固定版本，迁入后 pyproject.toml 里也是 ==。可以考虑改成 >=，让 uv.lock 负责固定版本。

升级某个库到新版本

$ uv tree --outdated --depth 1                 # 1. 看看哪些直接依赖有新版本
$ uv sync --upgrade-package typesafe-sdk      # 2. 在允许的范围内升到最新，并立即装上
$ uv run main.py                               # 3. 跑一遍，确认新版本没带来问题
$ git add uv.lock && git commit -m "upgrade typesafe-sdk"   # 4. 提交新的 uv.lock

第 2 步只改 uv.lock 和 .venv，pyproject.toml 保持不变。如果新版本超出了 pyproject.toml 里的范围（比如你写了 <1，而新版是 1.0），就要改用 uv add "typesafe-sdk>=1.0"，它会同时提高下限。所有升级方式的对比见 第 9 课 ③。

同事加了新依赖，你 git pull 之后

$ git pull          # 拿到了新的 pyproject.toml 和 uv.lock
$ uv sync           # 按新的 uv.lock 装上新包、删掉被移除的包

直接 uv run 也能把新包装上，但同事删掉的包会残留在你的 .venv 里（只补不删）。拉取后运行一次 uv sync 最稳妥。

不小心用 pip 装了包

如果这个包确实需要，用 uv add 包名 把它正式记录下来（已经装好的不会重复下载）；如果不需要，运行 uv sync，它会被自动清理掉。

环境出现奇怪的问题

$ rm -rf .venv     # 删掉"冰箱"。放心，清单和小票都还在
$ uv sync          # 按小票重新装满

在 VS Code 里使用

VS Code 需要知道用哪个解释器，否则会在 import 下画红色波浪线。按 ⌘ ⇧ P → 输入 "Python: Select Interpreter" → 选择 ./.venv/bin/python。通常 VS Code 也会自动检测到 .venv 并提示你选择它。

单文件脚本与临时工具

不是每段代码都值得建一个项目。写个一次性的小脚本，或者试一下某个库，uv 有更轻量的办法。

自带依赖声明的脚本（PEP 723）

Python 有一个标准（PEP 723），允许把依赖直接写在脚本文件的开头，用一段特殊注释表示。uv 可以读懂它：

$ uv init --script hello.py
$ uv add --script hello.py rich

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "rich>=15.0.0",
# ]
# ///


def main() -> None:
    print("Hello from hello.py!")


if __name__ == "__main__":
    main()

运行时 uv 读取这段注释，自动为这个脚本准备一个临时环境（放在缓存里，不会生成 .venv），装好 rich，然后运行：

$ uv run hello.py
Installed 4 packages in 4ms
Hello from hello.py!

这个文件可以直接发给别人。只要对方装了 uv，uv run hello.py 就能跑起来，不需要任何其他文件。它相当于把一个迷你版的 pyproject.toml 塞进了脚本里。

临时多加一个包：--with

想在不改动项目的情况下试一个库：

$ uv run --with rich python -c "import rich; print('ok')"
Installed 4 packages in 4ms
ok

rich 只存在于这一次运行里，pyproject.toml、uv.lock、.venv 都不会被改动。

命令行工具

像 ruff、pytest 这类"装了之后在终端里用"的工具，有 uvx、uv tool install、uv add --dev 三种装法，区别见 第 9 课。

应用与包：src 结构是怎么回事

uv 0.12 的 uv init 默认生成"包"结构，示例项目 jev-cli 用的是更简单的"应用"结构。这一课讲清楚两者的区别。

包结构实际长什么样

用 uv init pkgdemo --package 新建一个示例，下面是它的真实内容：

$ uv run pkgdemo
Using CPython 3.13.15
Creating virtual environment at: .venv
   Building pkgdemo @ file:///…/pkgdemo      # ← 先把项目自己打包
      Built pkgdemo @ file:///…/pkgdemo
Installed 1 package in 1ms                    # ← 装进自己的 .venv
Hello from pkgdemo!

安装后，.venv/bin/ 里多了一个 pkgdemo 命令文件，这就是 [project.scripts] 的效果。

改了代码要重新安装吗？

不用。uv 以"可编辑"方式安装项目自身，它指向的就是你 src/ 里的源代码，改完下次 uv run 直接生效。只有改了 pyproject.toml 里的 [project.scripts]（比如新增一个命令）时，才需要 uv sync 一下，让新命令出现在 .venv/bin/ 里。

读懂报错

下面每个报错都是写作时实际触发的。每个都按"现象 → 原因 → 怎么办"来拆解。

$ python3 main.py
ModuleNotFoundError: No module named 'dotenv'

$ uv add "typesafe-sdk>=0.7" "pydantic<2"
  × No solution found when resolving dependencies:
  ╰─▶ Because typesafe-sdk>=0.7.0 depends on pydantic>=2.12.0 and your
      project depends on pydantic<2, we can conclude that your project and
      typesafe-sdk>=0.7.0 are incompatible.
      And because your project depends on typesafe-sdk>=0.7, we can conclude
      that your project's requirements are unsatisfiable.

$ uv add typesafe-sdk          # 在一个 requires-python = ">=3.9" 的项目里
  × No solution found when resolving dependencies for split (markers:
  │ python_full_version == '3.9.*'):
  ╰─▶ Because the requested Python version (>=3.9) does not satisfy
      Python>=3.10 and all versions of typesafe-sdk depend on Python>=3.10, we
      can conclude that all versions of typesafe-sdk cannot be used.
      …
hint: The `requires-python` value (>=3.9) includes Python versions that are not
supported by your dependencies (e.g., all versions of typesafe-sdk only supports
>=3.10). Consider using a more restrictive `requires-python` value (like >=3.10).

$ uv add typesafe-sdkk
  × No solution found when resolving dependencies:
  ╰─▶ Because typesafe-sdkk was not found in the package registry and your
      project depends on typesafe-sdkk, we can conclude that your project's
      requirements are unsatisfiable.

$ uv run --locked main.py
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.
hint: To update the lockfile, run `uv lock`.

通用排错技巧

• 读到最后。uv 的 hint: 行往往直接给出解决办法。
• 加 -v 看详细过程，比如 uv sync -v，能看到 uv 在哪一步、用了哪个解释器、从哪里下载。
• 重建环境。rm -rf .venv && uv sync 能解决大多数"莫名其妙"的问题。
• 确认版本。uv --version、uv run python --version。

其他常见问题

自测与速查

先自己想一想，再点开看答案。能答对大部分，说明你已经掌握了 uv 的核心。

速查表