企业官网建设流程全解析

uv self update 实战指南：升级、降版本、团队对齐，3 条命令搞定

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv

$ uv self update error: Self-update is only available for uv binaries installed via the standalone installation scripts.

如果你刚用pip install uv装好 uv，然后兴冲冲跑uv self update，大概率会撞上上面这句报错。uv（Astral 用 Rust 写的 Python 包管理器）的自更新只有一条命令，但版本升级这件事里一半的坑，都在"你的 uv 是怎么装上的"。这篇按真实场景讲：第一次升级报错怎么解、怎么装回旧版本、团队里 uv 版本不一致怎么办、升级翻车怎么救回来。

第一次升级报错？先确认 uv 的安装方式

uv self update只认**独立安装脚本（standalone installer）**装出来的 uv。判断依据是一个收据文件：uv 装的时候会写一份uv-receipt.json（默认在~/.config/uv/uv-receipt.json），自更新时先读它。没有收据，直接报上面那句错，并提示你用pip install --upgrade、brew upgrade之类的方式升级。

所以第一步永远是看你的 uv 到底是谁装的：

which uv uv --version

• ~/.local/bin/uv（或~/.cargo/bin/uv）——独立脚本装的，可以继续用uv self update
• ~/venvs/.../bin/uv或 pip 装的路径——自更新不可用，用pip install --upgrade uv
• Homebrew 装的——brew upgrade uv

还有一种更隐蔽的情况：机器上有两份 uv，PATH 里排在前面的那份不是独立脚本装的。此时报错会直接告诉你两个路径：

error: The current executable is at `/usr/local/bin/uv` but the standalone installer was used to install uv to `/home/you/.local/bin/uv`. Are multiple copies of uv installed?

用which -a uv把所有 uv 找出来，把顺序理顺，问题就解决了一半。

一条命令完成升级

确认安装方式没问题后，uv 如何升级到最新版本就很简单了：

uv self update

它做的事情：读当前版本 → 查最新 release → 下载对应平台的uv-installer.sh（或 Windows 下的uv-installer.ps1）→ 重新执行一遍安装脚本，装回原来的目录，缓存和配置都不动。输出大概是：

info: Checking for updates... success: Upgraded uv from v0.9.4 to v0.9.14!

升级会重跑安装脚本，理论上可能再改一次 shell 配置；不想让它动，加一个环境变量：

UV_NO_MODIFY_PATH=1 uv self update

另外两个参数值得记住：

# 只看有没有新版本，不动手 uv self update --dry-run # GitHub API 限流（403）时带上 token uv self update --token ghp_xxx # 或设 UV_GITHUB_TOKEN

--dry-run的输出是Would update uv from v0.9.4 to v0.9.14，CI 里先 dry-run 再决定要不要真升级，是个稳妥的习惯。

安装指定版本与降版本

很多人不知道的是：uv self update后面可以直接跟一个精确版本号，而且可以用来降级。

uv self update 0.10.4 # 升级到 0.10.4 uv self update 0.6.0 # 降回 0.6.0，输出会显示 Downgraded uv from ... to ...

两个细节容易踩坑：

• 版本号必须写成完整的主.次.补丁三段，比如0.10.4。传0.10或v0.10.4会被直接拒绝，报错提示 "explicit versions must include an exact major.minor.patch release"。
• 没有--patch、--minor、--rollback这类模糊参数，想回到旧版本就老老实实写死版本号。

所以"回滚"这件事 uv 没有单独做命令，降版本就是它本身。

团队里 uv 版本不一致怎么办

场景很常见：你上周升级到了 0.10，同事还停在 0.8，同一个uv.lock解析出不一样的结果，互相怀疑对方依赖写错了。uv 本身没有"强制最低版本"这样的开关，对齐版本得靠约定加固定版本安装，成本其实很低：

1. 项目文档里写死当前使用的 uv 版本号（比如0.10.4），新人入职照着装；
2. 需要统一时，让所有人跑同一条命令：uv self update 0.10.4，装的是完全一样的二进制；
3. CI 里最干净：每次都用独立脚本装指定版本，而不是依赖 runner 上残留的 uv。

配合uv --version写进 CI 的第一步做检查，版本一旦漂移，pipeline 第一行就会红，比等人发现快得多。

升级失败怎么排查和救回来

按报错对号入座：

error: Self-update is not possible because network connectivity is disabled

你带了--offline，自更新依赖网络，去掉即可。

error: GitHub API rate limit exceeded. Please provide a GitHub token via the `--token` option.

共享 IP 触发了限流，加--token或设UV_GITHUB_TOKEN。

error: The current executable is at `...` but ... Are multiple copies of uv installed?

机器上有多份 uv，回到第一节的which -a uv处理。

升级装坏了怎么救？顺序很简单：

1. 新 uv 二进制还在能跑的：uv self update 0.6.0直接降回去；
2. 二进制本身起不来了：删掉它，重新跑一遍独立安装脚本装回任意版本——收据文件还在~/.config/uv/，装完uv self update依然可用。

最后一句提醒：用UV_UNMANAGED_INSTALL装的"无人管理模式"（常见于 CI）会主动关闭自更新，这是设计如此，别在这上面浪费排查时间。

现在就打开终端跑一条uv self update --dry-run，看看你的 uv 离最新版本差几轮。

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv