· 1 min read · AI开发工具

uv 0.13.9 预览支持 PEP 832 .venv 重定向文件:本机实测

2026 年 11 月 17 日发布的 uv 0.13.9 把 PEP 832 .venv 重定向文件列为预览特性。本文在本机下载并校验官方二进制,建立外部虚拟环境、把项目里的 .venv 换成一行重定向文件,实测 uv python find、uv sync、uv run 和 uv pip list 的解析结果,并记录告警开关、路径写法与几种失败情形。

2026 年 11 月 17 日,astral-sh/uv 发布 0.13.9。发布说明的「Preview features」一节写着:支持用于项目环境的 PEP 832 .venv 重定向文件(#21822)。本篇记录 2026 年 11 月 19 日在本机的一次命令行实测:下载并校验官方二进制、在项目目录外面建一个虚拟环境、把项目里的 .venv 换成一行指向它的文本,然后看 uv 的各条命令实际解析到哪里。这项能力仍是 preview,发布说明和命令输出都提示行为可能变化;本文只陈述这次本机看到的结果。

项目目录、.venv 重定向文件与外部虚拟环境的关系示意图,非软件界面截图

发布说明里写了什么#

0.13.9 发布页由 astral-releases-bot 发布,说明开头写着「Released on 2026-11-17」。预览特性列了两条:PEP 832 .venv 重定向文件(#21822),以及把 http2-keep-alive 加进预览特性,用于关闭仍有活动请求但无响应的 HTTP/2 连接(#23236)。同页还列出锁文件格式与读取性能、若干 bug 修复,以及「Raise the minimum supported Rust version to 1.98」(#23263)。发布说明没有把重定向文件写成默认稳定行为,也没有列出完整的边界规则。

PEP 832 定义了什么#

PEP 832《Virtual environment discovery》 当前状态是 Draft,类型为 Standards Track,主题 Packaging,创建于 2026-01-19。它在规范部分写道:项目根目录的 .venv 既可以是装着 pyvenv.cfg 的目录,也可以是一个重定向文件,文件里只有一行路径,指向当前应当使用的虚拟环境。路径可以是相对路径或绝对路径,允许使用 POSIX 的 / 分隔符;末尾的 \n 或 \r\n 会被忽略,空文件以及只有换行的文件算无效。

PEP 还写明:如果工具能检测到用户已经激活了某个环境(例如设置了 VIRTUAL_ENV),应当优先使用用户选中的环境;至于 .venv 无效时该怎么处理,这一版 PEP 明确不表态,由遇到它的工具自己决定。这两点在下面的实测里都能看到 uv 自己的处理方式。

流程#

flowchart TD
    A[下载 uv 0.13.9 并核对校验和] --> B[初始化项目并在外部创建虚拟环境]
    B --> C[把项目 .venv 目录换成一行重定向文件]
    C --> D[用 uv python find 核对解析路径与实验性告警]
    D --> E[用 sync / run / pip list 核对命令进入的环境]
    E --> F[换路径写法与无效目标,记录报错与回退]

告警开关示意:关掉警告不等于脱离 preview,非软件界面截图

下载与版本核对#

从 GitHub Release 下载 uv-x86_64-unknown-linux-gnu.tar.gz,用发布页提供的校验文件核对哈希后解压,全程只写本次工作目录:

PRTCL // BASH
Terminal window
cd tools
curl -fsSLO https://github.com/astral-sh/uv/releases/download/0.13.9/uv-x86_64-unknown-linux-gnu.tar.gz
curl -fsSLo uv-0.13.9.sha256 https://github.com/astral-sh/uv/releases/download/0.13.9/uv-x86_64-unknown-linux-gnu.tar.gz.sha256
sha256sum -c <(sed 's| .*| uv-x86_64-unknown-linux-gnu.tar.gz|' uv-0.13.9.sha256)
tar xzf uv-x86_64-unknown-linux-gnu.tar.gz
./uv-x86_64-unknown-linux-gnu/uv --version
PRTCL // TEXT
uv-x86_64-unknown-linux-gnu.tar.gz: OK
uv 0.13.9 (x86_64-unknown-linux-gnu)

本机系统 Python 是 3.13.5。

建项目与外部虚拟环境#

把 uv 的解压目录加进 PATH,初始化一个空项目,再用 uv venv 在项目外面建一个普通虚拟环境。uv venv --help 里没有写重定向文件的选项,所以重定向文件是本次手动写的:先删掉 uv init 建出来的 .venv 目录,再写入一行相对路径。

PRTCL // BASH
Terminal window
cd work && mkdir -p demo && cd demo
uv init hello --python /usr/bin/python3
cd hello
uv venv ../envs/external --python /usr/bin/python3
rm -rf .venv
printf '../envs/external\n' > .venv
PRTCL // TEXT
Initialized project `hello` at `/workspace/blog-daily-20261119/work/demo/hello`
Using CPython 3.13.5 interpreter at: /usr/bin/python3
Creating virtual environment at: ../envs/external
Activate with: source ../envs/external/bin/activate

uv python find 的告警与开关#

不带开关解析时,命令给出了实验性告警,但仍返回被指向环境的解释器路径:

PRTCL // BASH
Terminal window
uv python find
PRTCL // TEXT
warning: Using `.venv` redirect files is experimental and may change without warning. Pass `--preview-features venv-redirect-files` to disable this warning.
/workspace/blog-daily-20261119/work/demo/envs/external/bin/python

按告警给出的开关再跑一次,解析结果相同,警告消失:

PRTCL // BASH
Terminal window
uv python find --preview-features venv-redirect-files
uv python find --preview-features venv-redirect-files --show-version
PRTCL // TEXT
/workspace/blog-daily-20261119/work/demo/envs/external/bin/python
3.13.5

这个开关只影响告警,不改变解析规则,也不意味着特性已经稳定。

项目命令进入被指向的环境#

uv sync 把项目本身可编辑安装进了外部环境;uv pip list 显示了这条安装记录;uv run 执行的解释器也来自同一个环境。三条命令在没有加开关时都会给出同一条实验性告警,下面把告警各保留一行,便于对照:

PRTCL // BASH
Terminal window
uv sync
PRTCL // TEXT
warning: Using `.venv` redirect files is experimental and may change without warning. Pass `--preview-features venv-redirect-files` to disable this warning.
Resolved 1 package in 2ms
Building hello @ file:///workspace/blog-daily-20261119/work/demo/hello
Built hello @ file:///workspace/blog-daily-20261119/work/demo/hello
Prepared 1 package in 5ms
Installed 1 package in 1ms
+ hello==0.1.0 (from file:///workspace/blog-daily-20261119/work/demo/hello)
PRTCL // BASH
Terminal window
uv pip list
PRTCL // TEXT
warning: Using `.venv` redirect files is experimental and may change without warning. Pass `--preview-features venv-redirect-files` to disable this warning.
Using Python 3.13.5 environment at: /workspace/blog-daily-20261119/work/demo/envs/external
Package Version Editable project location
------- ------- ----------------------------------------------
hello 0.1.0 /workspace/blog-daily-20261119/work/demo/hello
PRTCL // BASH
Terminal window
uv run python -c 'import sys, hello; print(sys.executable); print(hello.__file__)'
PRTCL // TEXT
warning: Using `.venv` redirect files is experimental and may change without warning. Pass `--preview-features venv-redirect-files` to disable this warning.
/workspace/blog-daily-20261119/work/demo/envs/external/bin/python
/workspace/blog-daily-20261119/work/demo/hello/src/hello/__init__.py

路径写法与无效目标#

相对路径写成 CRLF 行尾、或者换成绝对路径,都能解析到同一个解释器:

PRTCL // BASH
Terminal window
printf '../envs/external\r\n' > .venv
uv python find --preview-features venv-redirect-files
printf '%s\n' '/workspace/blog-daily-20261119/work/demo/envs/external' > .venv
uv python find --preview-features venv-redirect-files
PRTCL // TEXT
/workspace/blog-daily-20261119/work/demo/envs/external/bin/python
/workspace/blog-daily-20261119/work/demo/envs/external/bin/python

空文件会直接报错,退出码是 2:

PRTCL // BASH
Terminal window
: > .venv
uv python find --preview-features venv-redirect-files
PRTCL // TEXT
error: Virtual environment redirect file at `.venv` is empty

目标路径不存在时,uv python find 没有报错,而是退回到系统解释器:

PRTCL // BASH
Terminal window
printf '../envs/does-not-exist\n' > .venv
uv python find --preview-features venv-redirect-files
PRTCL // TEXT
/usr/bin/python3.13

但对项目环境来说,这个目标不能直接使用。uv sync --dry-run(dry run 不写锁文件、不改动环境)报的是目标目录没有 pyvenv.cfg:

PRTCL // BASH
Terminal window
uv sync --dry-run --preview-features venv-redirect-files
PRTCL // TEXT
error: Project virtual environment directory `/workspace/blog-daily-20261119/work/demo/hello/../envs/does-not-exist` cannot be used because no `pyvenv.cfg` file was found

这里也能看出 PEP 说的「无效时怎么办由工具决定」:uv python find 选择回退,uv sync 选择报错。另外,uv pip list 在目标不是有效虚拟环境时会落到系统 /usr 解释器并列出系统站点包;这里不粘贴本机那份包清单。

有效目标、目标不存在和目标不是虚拟环境的三条分支示意图,非软件界面截图

环境覆盖与子目录#

把 VIRTUAL_ENV 指向另一个虚拟环境后,uv python find 优先采用它,不再读项目里的重定向文件:

PRTCL // BASH
Terminal window
printf '../envs/external\n' > .venv
VIRTUAL_ENV=/workspace/blog-daily-20261119/work/envs/other uv python find --preview-features venv-redirect-files
PRTCL // TEXT
/workspace/blog-daily-20261119/work/envs/other/bin/python

子目录里的 .venv 重定向文件也能解析,路径相对于该文件所在的目录计算:

PRTCL // BASH
Terminal window
mkdir -p sub
printf '../../envs/external\n' > sub/.venv
cd sub && uv python find --preview-features venv-redirect-files
PRTCL // TEXT
/workspace/blog-daily-20261119/work/demo/envs/external/bin/python

最后,对一个已经是重定向文件的 .venv 再执行 uv venv,uv 不会把文件替换成目录,而是直接失败:

PRTCL // BASH
Terminal window
uv venv .venv --preview-features venv-redirect-files
PRTCL // TEXT
Using CPython 3.13.5 interpreter at: /usr/bin/python3.13
Creating virtual environment at: .venv
error: Failed to create virtual environment
cause: File exists at `.venv`

清理#

实测结束后,删除本次的 work/demo/ 目录和 tools/ 下的二进制与压缩包,不保留本机副本。本次没有启动常驻服务,也没有改动系统 Python 或仓库配置。上传到公开图床的图片不在此列。

边界#

发布说明把这项能力列在预览特性里,命令输出也写明「experimental and may change without warning」;--preview-features venv-redirect-files 在本机只是让告警不再出现。本篇验证的是相对路径、绝对路径、CRLF 行尾、空文件、目标不存在、VIRTUAL_ENV 覆盖、子目录查找,以及 uv venv 遇到已有重定向文件时的行为;没有验证 Windows 上的路径语义、符号链接路径、锁文件在团队间的共享方式,也没有验证其他工具读取重定向文件时的表现。上面那些路径、退出码和输出只对应这次本机运行。

Comments

Copied
Copied to clipboard