PEP 751 pylock.toml 实测:pip 26.3 装 6 个包版本全钉死,但 web 选不中任何东西
今天早上我跑 pip install -r pylock.toml,第一把就报错了。
ERROR: Can't verify hashes for these file:// requirements because they point to directories:
file:///tmp/pylock-lab/demo/ (from pylock.toml)
锁文件是 pip 26.3 自己刚生成的,安装也是 pip 26.3 自己做的,同一台机器、同一个命令,前后脚------写锁的那边觉得没问题,装锁的那边直接拒收。这就是 PEP 751 pylock.toml 在 2026 年 11 月的真实状态:标准已经 Final,写锁、装锁的工具链都齐了,可你真把它当成"标准锁文件"用,头三步就能踩到三个不同的坑。
这篇不讲概念,讲我今天早上在 Python 3.12.3 + pip 26.3 上一手跑出来的东西:pip lock 写出来的文件长什么样、从锁安装到底钉死了什么、改一个哈希会发生什么、pip 26.3 新加的 [extra] 和 --group 语法什么时候管用、什么时候是摆设。所有版本号、报错原文、包的数量,都是 2026-11-17 当天实测。
先说清它是什么:装箱单,不是购物清单
一个类比,全文只用这一个:pyproject.toml 是购物清单------写着你要什么(requests>=2.31);pylock.toml 是装箱单------写着仓库实际给你装了哪个批次、哪个文件、哈希是多少(requests 2.34.2,具体某一个 wheel 文件,sha256 是多少)。购物清单可以年年用,装箱单只对这一单有效;反过来,拿着装箱单,任何一家仓库都能原样复现这一单,不用再去问"2.31 以上到底是哪个版本"。
PEP 751 就是给这张装箱单定格式。作者 Brett Cannon,2024-07-24 立项,2025-03-31 正式通过(Status: Final),文件就叫 pylock.toml,或者 pylock.<名字>.toml(比如生产一份、开发一份)。格式是 TOML,人能读,机器能直接按图索骥,不用在安装时再跑一次依赖解析。
这不是 Python 社区第一次想统一锁文件格式。上一次是 PEP 665(2021 年),同样想定一个标准锁文件,结果被拒了------主要毛病是它只支持 wheel,不支持源码分发(sdist),等于把一大半真实项目挡在门外。PEP 751 吸取了这个教训:wheel、sdist、VCS、本地目录、归档文件,五种来源都能记,每种都带哈希和大小。
时间线要钉死,免得有人把功劳算错年份:
| 时间 | 事件 |
|---|---|
| 2021 | PEP 665 提出标准锁文件,因不支持 sdist 被拒 |
| 2024-07-24 | PEP 751 立项 |
| 2025-03-31 | PEP 751 正式通过,Status Final |
| 2025-04-26 | pip 25.1 加入实验性 pip lock 写锁 |
| 2026-01-18 | Poetry 2.3.0 可导出 pylock.toml |
| 2026-04-26 | pip 26.1 加入实验性 pip install -r pylock.toml |
| 2026-07-29 | pip 26.2 补 upload-time、--only-final |
| 2026-11-02 | pip 26.3 支持 [extra]、--group、--no-binary |
注意这个时间线里有个容易被忽略的点:PEP 本身 2025 年 3 月就 Final 了,但"能用"这件事是 pip 一点一点补齐的------写锁等了 26 天,装锁等了一年多,extras 和依赖组的选择又等到 2026 年 11 月 2 日的 pip 26.3 才补上。你今天看到的很多中文文章还在写"pip 还不支持从 pylock.toml 安装",那是 26.1 之前的旧闻。
文件名的规矩也顺带说清:默认就叫 pylock.toml,想放多份就用 pylock.<名字>.toml,比如 pylock.dev.toml 放开发依赖、pylock.prod.toml 放生产依赖,名字里不能带点。PEP 还给云厂商留了个约定:一个叫 spam 的托管服务,会先找 pylock.spam.toml,找不到再找 pylock.toml 里有没有名叫 spam 的依赖组,最后才用默认安装。这个约定今天还没几个服务真的实现,但它说明了一件事------这套格式从一开始就是按"别人替你装"来设计的,不是按"你自己装"设计的。
还有一句必须先讲清楚,PEP 原文里写了好几遍:pylock.toml 是安装时产物,不是各工具自有锁文件的替代品。uv.lock、poetry.lock、pdm.lock 该用还用,pylock.toml 是它们往外倒的"通用格式",好让 pip、云厂商、审计工具这些不是你包管理器的人也能照着装。指望它一夜之间取代 uv.lock 的,可以先打住了。
锁文件里到底写了什么:逐行拆开看
我拿一个最小项目实测。pyproject.toml 只有两行依赖:
toml
[project]
name = "pylock-demo"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
"requests>=2.31",
"click>=8.1",
]
[project.optional-dependencies]
web = ["httpx>=0.27"]
[dependency-groups]
docs = ["mkdocs>=1.5"]
test = ["pytest>=8.0"]
跑 pip lock .(pip 26.3,实验性命令,会先打一行实验性警告),得到一份 pylock.toml。requests 那一段长这样(哈希是完整值,可直接对照校验):
toml
lock-version = "1.0"
created-by = "pip"
[[packages]]
name = "requests"
version = "2.34.2"
[[packages.wheels]]
name = "requests-2.34.2-py3-none-any.whl"
url = "https://files.pythonhosted.org/packages/a0/f4/c67b0b3f1b9245e8d266f0f112c500d50e5b4e83cb6f3b71b6528104182a/requests-2.34.2-py3-none-any.whl"
[packages.wheels.hashes]
sha256 = "2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0"
整份文件锁定了 7 个条目:6 个第三方包 certifi 2026.10.23、charset-normalizer 3.5.2、click 8.5.1、idna 3.20、requests 2.34.2、urllib3 2.8.0,再加上项目本身 pylock-demo(以 [packages.directory] path = "." 的形式记进去,没有版本号)。注意三点:
第一,requests>=2.31 这种范围被解析成了精确的 2.34.2,而且连 requests 的四个间接依赖(charset-normalizer、idna、urllib3、certifi)也一并钉死。装箱单的意义就在这里:范围只在写锁那一刻存在,装的时候没有任何"再解析一次"的空间。
第二,每个 wheel 都带了完整的 URL + sha256。安装时 pip 会先校验哈希再装,哈希对不上直接拒装------这段我实测过,把 requests 的哈希改成一串 0,pip 的报错是原文:
ERROR: ... hash mismatch ...
Expected sha256 0000000000000000000000000000000000000000000000000000000000000000
Got 2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0
第三,pip 自己写出来的锁,有两个"没写"的地方值得留意。文件里没有 requires-python,没有 environments,也没有 extras / dependency-groups 这些顶层字段------尽管我的 pyproject 里明明定义了 web 这个 extra 和 docs、test 两个依赖组。pip 的写锁目前是单用途的:它只锁当前这次解析出来的包集合,extras 和依赖组的信息直接丢了。这不是 bug,PEP 明确允许 locker 只写单用途锁("Lockers MAY support writing lock files that utilize the proposed marker expression syntax"------可以支持,也可以不支持)。但后果很实在,后面讲 [web] 那节会撞上。

图注:pip 26.3 的 pip lock 对两行依赖解析出的 6 个第三方包(另有项目本身一条目录记录)。注意文件里没有 extras、dependency-groups、requires-python------这些字段 pip 目前不写。
它怎么做到"不用解析就能装":locker 和 installer 分工
理解 pylock.toml 的关键是分清两个角色,PEP 原文就这么叫:locker(写锁的人)和 installer(装锁的人),可以是同一个工具,也可以不是。
写锁那一步,locker 干的是解析的活:读你的 pyproject 或 requirements,把 requests>=2.31 这样的范围解成精确版本,再把每个包的 wheel 地址、大小、哈希、上传时间一一记下来。解析只发生在这里,而且只发生一次。
装锁那一步,installer 照单抓药,PEP 把步骤写死了,大意是:先看 lock-version 支不支持,再核对 requires-python 和 environments,然后对每个包检查它的 marker 过不过------marker 不满足就跳过,满足就按写明的 URL 下载、校验大小和哈希、安装。全程不跑解析器,不问 PyPI"现在最新版是多少"。
这个分工带来两个直接好处。第一是快:安装是最频繁的操作,解析是最贵的操作,把解析挪到写锁那一次,安装就只剩下载和校验。第二是可审计:锁文件是 TOML 文本,created-by 写明是谁生成的,[tool] 表还能记生成命令,review 的时候能逐行看"到底装了什么",而不是对着一行 requests>=2.31 猜。
但也有一个反直觉的点:锁文件不记录"输入是什么" 。PEP 明确说了,不记生成这把锁用的 requirement 输入。也就是说,三个月后你拿着 pylock.toml,能知道装了什么,但不知道当初是拿 requests>=2.31 还是 requests==2.34.2 锁出来的。想复现"重新锁一次得到同样结果",得靠你自己把 pyproject 和生成命令也留好。装箱单不记你当初是怎么下单的,只记发了什么货。

图注:Archify 架构图。左边四种写锁方式(pip lock、uv export、Poetry 导出、PDM)都能产出同一格式的锁文件,右边 pip install、pylock-lint、云厂商/CI 都只认这一种格式。
安装时到底发生了什么:PEP 写死的六步
PEP 751 把安装过程写成了一张清单,installer 必须按这个顺序走。我把它翻译成大白话,你对照着看,pip 今天的行为基本就是这套:
- 先算你要装什么 :把用户这次点的 extras 和依赖组算成两个集合。默认情况下 extras 是空集,依赖组取
default-groups里写的那几个。我手写那把锁把default-groups设成空数组,所以默认安装时两个集合都是空的,带 marker 的包全跳过。 - 核对格式版本 :读
lock-version,现在唯一合法的值是"1.0"。大版本号对不上必须报错,小版本号对不上应当警告------给未来升级留的口子。 - 核对 Python 版本和环境 :
requires-python写了就检查当前 Python 够不够格,不够直接报错;environments写了就检查当前环境至少满足其中一条,一条都不满足也报错。 - 逐包过 marker :每个
[[packages]]先算它的marker,不满足就跳过------这就是[web]和--group生效的地方,也是 uv 扁平导出让选择器失效的原因:没有 marker 可算,全部默认装。 - 防冲突:同一个包不能出现两个要装的版本,来源也不能自相矛盾(比如一个包既写了 wheel 又写了目录)。有冲突必须报错,不能悄悄挑一个。
- 下载、校验、安装:按写明的 URL 取文件,先对大小和哈希,过了再装。轮到 wheel 时按文件名挑对当前平台的那一个,挑不到就去找 sdist,sdist 也没有就报错。
注意第 6 步里的顺序:校验在安装之前。pip 今天就是这么做的------前面改哈希那次,报错发生在安装之前,venv 里一个包都没装进去。这也是锁文件和 requirements.txt 在安全上最实在的区别:requirements.txt 的哈希是可选项,不写也能装;pylock.toml 的哈希是必选项,不对就拒装。
省时间吗:实测 6 个包,锁和不锁只差 0.2 秒
"安装不用解析,所以更快"这句话,我今天顺手量了一下。同一台机器、同一个空 venv、wheel 全是缓存命中的情况:
pip install -r pylock.toml(6 个包):2.48 秒pip install -r requirements.txt(同样 6 个包,走解析器):2.72 秒
只差 0.2 秒,基本可以忽略。别被"不用解析所以更快"这句话带偏:包少、缓存热的时候,解析器的开销本来就微不足道。锁文件真正的速度收益在两个地方:一是依赖上百个、解析要跑几十秒的大项目,二是冷缓存、弱网环境下"不用反复问索引"。小项目上,它省的不是时间,是"这次装的和上次装的是不是同一批东西"这个不确定性。速度是附赠的,确定性才是正餐。
谁最需要这张装箱单
写到这里可以回头想想,PEP 751 到底是为谁写的。答案不在个人开发者身上------个人项目用 pip-tools 或者 uv.lock 早就够用了。它真正服务的是那些"不是你的包管理器、却要替你装包"的人。
Dependabot 是第一个。GitHub 的依赖更新机器人要给你的项目提"requests 2.34.2 → 2.35.0"的 PR,它得先读懂你的锁文件。今天它要分别适配 poetry.lock、uv.lock、pdm.lock、pip-tools 的 requirements.txt,每种格式各写一套解析。有了统一格式,它只要会读 pylock.toml 一种。
云厂商是第二个。部署平台、Serverless、CI 镜像这些地方,装依赖是平台替你干的活。平台不可能为了每种包管理器各装一套工具链,它只想认一种文件:你交一把锁,我照着装。Cloudflare 的 pywrangler 已经这么干了------用 uv 解析出 pylock.toml,再按它安装。
审计和合规是第三个。一份锁文件同时给出精确版本、文件地址、哈希、上传时间、来源证明(attestation-identities),审计人员不用再拼凑"生产环境到底装了什么"。标准格式的意义在这里最实在:审计工具只要实现一次 PEP 751,就能审所有工具生成的锁。
所以看 pylock.toml 别只看 pip------pip 只是第一个把它落地的工具。这张装箱单的真正价值,在它成为"交接格式"的那天才兑现。而那一天,取决于有多少工具愿意往这个格式里倒数据。今天的进度是:uv 和 Poetry 能导出,PDM 能直接用,pip 两侧实验性。离"各方都认"还有一段路,但至少,路已经通了。
文件结构上,值得展开说的有三块。
[[packages]] 每一条就是一个包 :name + version 是必记的;来源五选一------[packages.vcs](Git 地址 + commit-id)、[packages.directory](本地路径)、[packages.archive](归档 URL)、[packages.sdist]、[[packages.wheels]]。每种来源都带 size 和 hashes,哈希表至少要有一项。packages.index 记它是从哪个索引来的,packages.requires-python 记这个包最低要哪个 Python。
upload-time 是个容易被低估的字段 :每个 wheel/sdist 都能记上传到 PyPI 的时间。pip 26.2 开始支持它,配合 --uploaded-prior-to,你能说"只装 2026 年 6 月 1 日之前上传的文件"。做合规、做复现、做"某天之后发布的版本不许进生产",靠的就是这个字段。
marker 是这套格式里最精巧、也最容易被写错的部分 。PEP 751 给环境标记加了两个新变量:extras 和 dependency_groups,都是集合。比如一个包只在用户选了 web 这个 extra 时才装,它的 marker 就写成:
toml
marker = "'web' in extras"
只在 test 依赖组里才装的,写成:
toml
marker = "'test' in dependency_groups"
还能组合布尔逻辑:'web' in extras or 'docs' in dependency_groups、'web' not in extras。安装器在装之前先把"用户这次要了哪些 extras、哪些组"算成两个集合,再逐包求值。格式本身支持多用途锁,写锁的工具跟不跟得上,是另一回事。
把一份锁文件从头读到尾:除了包名版本,还有四样东西值得会读
上面贴的只是 pip 生成的最小形态。一份"全乎"的 pylock.toml 还会带另外四样东西,读锁文件做评审的时候,盯的就是它们。
environments :一串环境标记表达式,声明这把锁对哪些环境有效,比如 ["sys_platform == 'win32'", "sys_platform == 'linux'"]。安装器装之前先算一遍:当前环境至少要满足其中一条,否则直接报错。这就是锁文件"自带适用范围"的意思------你不用再猜这份锁是给谁锁的。
[[packages.dependencies]]:每个包依赖了谁。注意,pip 和 uv 导出的锁目前都不写这一项(它们只列扁平的包清单),但格式是支持的。审计的时候这一项很有用:你想知道"requests 为什么会把 charset-normalizer 带进来",不靠猜,靠这张表。
[[packages.attestation-identities]] :包的来源证明。比如一个 wheel 是 GitHub Actions 里 python-attrs/attrs 仓库的 pypi-package.yml 工作流发布的,发布环境是 release-pypi,这些信息能写进锁里。配合 PyPI 的可信发布(Trusted Publishing),这就是"这个文件确实是那次 CI 跑出来的"那条证据链。供应链审计要的不是哈希本身,是哈希背后的出处。
[tool] 表:给生成工具留的自留地。PEP 的示例里,生成工具把自己的完整命令都记下来了:
toml
[tool.mousebender]
command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
run-on = 2025-03-06T12:28:57.760769
(这是 PEP 751 原文里的示例,不是我的实测数据------我贴它是为了说明格式长什么样。)三个月后有人问"这把锁到底是怎么锁出来的",答案不在聊天记录里,在文件自己身上。
上手:三条命令,从写锁到装锁
版本要求先钉死,免得你照着做却跑不通:写锁要 pip 25.1+,从锁安装要 pip 26.1+,[extra] 和 --group 选择要 pip 26.3+。我今天实测用的是 pip 26.3(2026-11-02 发布)、Python 3.12.3,uv 0.13.8 做对照。
写锁:pip lock
两种最常见的写法:
bash
# 对一个本地项目写锁(会把项目本身也锁进去,见下一节的坑)
pip lock .
# 对一份 requirements 写锁(干净,只锁第三方包)
pip lock -r requirements.txt
注意 -o 输出文件名也有限制:必须是 pylock.toml 或 pylock.<名字>.toml,<名字> 里不能带点。我实测 pip lock -r requirements.txt -o pylock-req.toml,pip 直接警告:
WARNING: pylock-req.toml is not a valid lock file name.
文件名里那个横杠 - 就是问题------pylock-req.toml 会被当成"名字里带横杠"吗?不,问题是 pylock-req.toml 不匹配 pylock.<名字>.toml 的模式吗?其实 req 里没有点,pylock-req.toml 的问题是分隔符必须是点不是横杠。写成 pylock.req.toml 就没问题。这个校验 pip 和 uv 都做,uv 的报错更直白:
error: Expected the output filename to be `pylock.toml` or `pylock.<name>.toml`,
where `<name>` is non-empty and contains no dots; found `pylock-uv.toml`
装锁:pip install -r pylock.toml
拿 pip lock -r requirements.txt 生成的那份干净锁,在一个全新的空 venv 里装:
bash
python -m venv fresh
fresh/bin/pip install -U pip # 升到 26.3
fresh/bin/pip install -r pylock.toml
输出我贴实测原文(图里是同一份输出的渲染版):
Collecting urllib3==2.8.0 (from pylock.toml)
Using cached urllib3-2.8.0-py3-none-any.whl (135 kB)
Installing collected packages: urllib3, idna, click, charset-normalizer, certifi, requests
Successfully installed certifi-2026.10.23 charset-normalizer-3.5.2 click-8.5.1 idna-3.20 requests-2.34.2 urllib3-2.8.0
装完 pip list 逐个核对:6 个包,版本和锁文件里写的一字不差。注意输出里的 urllib3==2.8.0 (from pylock.toml)------pip 把它当成精确版本要求,没有跑解析器,没有问 PyPI 还有没有更新的版本。requests>=2.31 在写锁那一刻就已经"死"了,死成 2.34.2。

图注:2026-11-17 实测,Python 3.12.3 + pip 26.3,全新空 venv。pip install -r pylock.toml,6 个包版本与锁文件完全一致。
验锁:改一个数,看它拦不拦你
锁文件的价值不在"写出来",在"被改了能不能发现"。我把 requests 的 sha256 改成一串 0 再装,pip 直接拒装,Expected / Got 两行哈希原样贴出来(前面已经贴过报错原文)。这个校验是强制的,不是可选项--------require-hashes 在读 pylock.toml 时是默认隐含开启的,你不用加任何 flag。
但这句话要说全:哈希校验防的是"文件在传输或存储中被换了",防不住"有人直接改锁文件本身"。PEP 原文在安全一节写得明白:格式本身不防篡改,改锁文件指向一个恶意版本,格式会老老实实照办。所以 pylock.toml 提交进仓库之后,靠的是代码评审和签名,不是靠格式自己。别把"带哈希"等同于"防投毒"。
重锁:加一行依赖,diff 长什么样
锁文件是要进版本控制的,diff 漂不漂亮直接决定它能不能被评审。我实测了一把:在 requirements 里加一行 rich>=13.0,重新 pip lock -r requirements.txt,diff 的结果很干净------
6 个包 → 10 个包
新增:rich 15.0.0、markdown-it-py 4.3.0、mdurl 0.1.2、pygments 2.21.0
原有 6 个包:版本号、URL、哈希,一行没动
diff 只有两处纯新增,没有一行是改动。PEP 对此有明确要求:工具写锁时"SHOULD"用稳定的键顺序、稳定的数组排序,就是为了让 diff 尽量小。pip 这点做得不错:包按字母排序,键的顺序固定。
这个性质决定了 pylock.toml 的日常工作流:升级某个包 = 改 requirements 里的范围 + 重新锁一次 + 审 diff 。pip lock 没有 --upgrade-package 这种单包升级选项(我翻了 pip lock --help,没有),想升 requests,先把 requests>=2.31 改成你想要的范围,再整把重锁。重锁之后审 diff 的时候盯三件事:有没有包的版本被连带抬了(比如 rich 把 pygments 顶到了 2.21.0)、有没有包的 URL 从 wheel 变成了 sdist、有没有多出你不认识的包。diff 里出现任何一个你说不上来由的名字,先别合,查清楚再说。
还有一个配套习惯:锁文件和生成它的输入要一起提交。pip lock -r requirements.txt 生成的锁,不记它是从哪份 requirements 锁出来的(前面说过,PEP 不记输入)。所以 requirements.txt 和 pylock.toml 必须成对进仓库,缺一个,另一个就成了孤儿------三个月后没人知道这把锁当初是按什么锁的。
进阶实战:手写一份多用途锁,三种装法结果全不一样
上面那节有个伏笔:pip 自己写出来的锁不带 extras 和依赖组信息。那 pip 26.3 新加的 [extra] 和 --group 语法,到底是给谁准备的?答案是:给"锁文件里真的写了这些信息"的情况准备的。pip 自己目前还写不出来,你得用别的工具导出,或者像我下面这样手写一份。
我拿 uv 0.13.8 导出的同一批包数据(uv export --format pylock.toml --all-extras --all-groups,解析出 31 个包),手工拼了一份多用途锁 pylock.multi.toml,关键就两处:文件头声明这把锁支持什么,包上挂 marker 声明"谁要我才装":
toml
lock-version = "1.0"
created-by = "hand-written demo (from uv 0.13.8 export data)"
requires-python = ">=3.12"
extras = ["web"]
dependency-groups = ["test"]
default-groups = []
[[packages]]
name = "requests"
version = "2.34.2"
# ... wheels + hashes,数据照 uv 导出原样抄
[[packages]]
name = "httpx"
version = "0.28.1"
marker = "'web' in extras"
# ... wheels + hashes
[[packages]]
name = "pytest"
version = "9.2.0"
marker = "'test' in dependency_groups"
# ... wheels + hashes
default-groups = [] 的意思是:不点名要组的时候,一个组都不装。requests 那几个没挂 marker 的包是默认集,httpx 一家挂 'web' in extras,pytest 一家挂 'test' in dependency_groups。然后在三个全新空 venv 里各装一次,结果如下(2026-11-17 实测,包数是 pip list 逐个数的):
| 装法 | 命令 | 装了几个包 | 有没有 httpx | 有没有 pytest |
|---|---|---|---|---|
| 默认 | pip install -r pylock.multi.toml |
6 | 没有 | 没有 |
| 选 extra | pip install -r 'pylock.multi.toml[web]' |
10 | 有(0.28.1) | 没有 |
| 选依赖组 | pip install --group pylock.multi.toml:test -r pylock.multi.toml |
11 | 没有 | 有(9.2.0) |
三行都符合预期。默认只装 requests 一家(certifi、charset-normalizer、idna、urllib3 加它自己,再加一个下面要说的 colorama------那是我第一次手写时漏标 marker 漏进来的,见坑那节);[web] 多了 httpx 全家(httpcore 1.0.9
、h11 0.16.0、anyio 4.16.0、typing-extensions 4.16.0);--group ...:test 多了 pytest 全家(iniconfig 2.3.1、packaging 26.3、pluggy 1.7.0、pygments 2.21.0)。装完我还跑了 import httpx, requests,两个都能正常 import,httpx 0.28.1、requests 2.34.2,版本号对得上。
图注:2026-11-17 实测包数。注意最右一根:uv 导出的扁平锁没有 marker,[web] 写了等于没写,31 个全装。
这张图最右那根柱子,就是这篇文章最想让你记住的结论:[extra] 和 --group 能不能过滤,不取决于 pip 26.3,而取决于锁文件里有没有写 marker。pip 26.3 只是"支持读",写锁的工具不写,语法就形同虚设。
同一份锁,uv 导出为什么选不中
为了把这句话钉死,我又拿 uv 0.13.8 的导出做了对照。uv export --format pylock.toml --all-extras --all-groups 导出的文件,31 个包全在里面------httpx、mkdocs、pytest 一个不少,但文件头只有三行:
toml
lock-version = "1.0"
created-by = "uv"
requires-python = ">=3.12"
没有 extras,没有 dependency-groups,31 个包里只有 2 个带 marker(还都是 sys_platform == 'win32' 这种平台标记)。于是:
bash
pip install -r 'pylock.all.toml[web]'
pip 不报错、不警告(除了那行实验性通告),老老实实把 31 个全装了------pytest 9.2.0、mkdocs 1.6.1 全在里面。你以为你只要了 web,结果测试和文档依赖也进了生产环境。uv 这么干不是 bug:uv 的定位是把 pylock.toml 当导出格式,uv.lock 才是它自己的主锁;导出时它选择"全量扁平",因为它自己的跨平台解析结果没法无损地塞进单用途的 marker 体系。这也是 PEP 允许的------locker 可以只写单用途锁。
所以今天的真实分工是这样的:pip 写锁是单用途,uv 导出是扁平全量,Poetry 2.3.0(2026-01-18 发布,需 poetry-plugin-export 1.10.0+)刚加上导出,同样还不能拿 pylock.toml 替代 poetry.lock;PDM 是目前走得最远的,可以直接把 pylock.toml 当项目主锁文件用(opt-in 的 pylock 格式)。想在一份锁里同时享受"一个文件、多种装法",今天只有手写,或者等写锁的工具跟上。
同一份依赖,pip 和 uv 写出来的锁差在哪
上面那组对照只说了"能不能选",还没说两份锁文件本身长得有多不一样。我把 pip 和 uv 对同一份依赖生成的锁逐项数了一遍,数字都在这儿:
pip 26.3 pip lock -r requirements.txt |
uv 0.13.8 uv export --format pylock.toml --all-extras --all-groups |
|
|---|---|---|
| 包数 | 6 | 31(含 httpx、mkdocs、pytest 全家) |
| 每个包带 sdist 吗 | 不带,只有 wheel | 带,31 个包全有 sdist |
| 带 upload-time 吗 | 不带,0 处 | 带,362 处 |
| 带 index 吗 | 不带 | 带,31 处(全是 pypi.org/simple) |
| wheel 覆盖几个 Python | 只锁当前 Python(cp312) | 同一个包列多个版本:watchdog 同时有 cp312、cp313、cp314、cp315、pp312、py3 的 wheel |
| 文件头 | 只有 lock-version + created-by | 多两行:requires-python = ">=3.12",还用注释记下了生成命令 |
| marker | 0 个 | 2 个(都是平台标记) |
这张表解释了为什么同样一份 pylock.toml,uv 导出的更适合当"交接件":它带 sdist,意味着目标机器上没有合适 wheel 的时候还能现场编译;它带 upload-time,--uploaded-prior-to 才能用;它一个包列多个 Python 版本的 wheel,同一把锁能在 3.12 到 3.15 上都装得起来。pip 的锁呢?它只保证"在我这台机器、这个 Python 上能原样重装",换台机器就得重锁。
反过来,uv 的导出也有代价:文件大得多(31 个包、每个包 sdist + 多个 wheel,带 362 个 upload-time),而且因为是全量扁平,前面说的 [extra] 失效问题就跟着来了。两家的取舍正好相反:pip 的锁小而专,uv 的锁全而扁。选哪个当交接件,看你更怕"换机器装不上"还是更怕"多装了测试依赖"。
还有一个小细节值得记:uv 导出的文件头用注释记下了生成命令(# uv export --format pylock.toml --all-extras --all-groups ...)。PEP 的 [tool] 表是结构化的做法,uv 用的是注释------效果一样,都是让三个月后的人知道这把锁是怎么来的。pip 的锁没有这一项,生成命令得你自己记。
搬到 CI 和 Docker 里:锁文件真正的用场
单机实测跑通之后,这东西在工程里的位置就清楚了。三个最实在的用法:
第一,CI 里把"解析"和"安装"拆开。 写锁在提交前做一次(pip lock -r requirements.txt),CI 里只装锁(pip install -r pylock.toml)。安装不再跑解析,CI 时间里最玄学的那一段("为什么上周跑得好好的这周解析出个新版本")直接消失。配合 --require-hashes 的默认开启,CI 装到的和你本地锁的是同一批文件,哈希不对就地失败。
第二,Docker 多阶段构建里当交接件。 构建阶段用 pip/uv 生成 pylock.toml,运行阶段只带锁文件和 pip 就能装,不用把 pyproject、uv.lock、Poetry 这些工具链全塞进镜像。云厂商和部署平台喜欢的就是这个:它们不用学会你的包管理器,只要会读一种格式。
第三,给锁文件加一道 lint。 PyPI 上已经有 pylock-lint 这种静态检查工具,读你提交的 pylock.toml,报单平台锁、单 Python 锁这些可移植性问题,CI 里非零退出就能拦住。我的建议是:如果你决定提交 pylock.toml,就顺手把这类检查接进 CI,否则"锁了但只在你机器上能用"这种问题,要到同事的 Mac 上才暴露。
一个最小的 GitHub Actions 片段长这样(思路,版本号按你项目改):
yaml
- name: Install from lockfile
run: |
python -m pip install --upgrade pip # 26.3+ 才有 [extra]/--group
pip install -r pylock.toml
- name: Lint the lockfile
run: pylock-lint --require-cross-platform
注意第一行的升级:很多 CI 镜像自带的 pip 还是 24.x/25.x,pip install -r pylock.toml 在 26.1 之前根本不存在,会直接报错"Could not open requirements file"。先升级 pip,再装锁,这个顺序别反了。
Docker 里也是同一个思路,锁文件是两个阶段之间的交接件:
dockerfile
# 阶段一:构建阶段,有全套工具链,负责写锁
FROM python:3.12-slim AS locker
WORKDIR /app
COPY pyproject.toml requirements.txt ./
RUN pip install -U pip \
&& pip lock -r requirements.txt
# 阶段二:运行阶段,只带锁文件和 pip,负责装锁
FROM python:3.12-slim AS runtime
WORKDIR /app
COPY --from=locker /app/pylock.toml ./
COPY app.py ./
RUN pip install -U pip \
&& pip install -r pylock.toml
CMD ["python", "app.py"]
这个 Dockerfile 我没在今天的环境里完整跑(手头没有 docker 守护进程,写进文章的就必须是没跑过的------所以这里明确标出来:思路示例,未实测,别直接照抄上生产)。但它想表达的那个分工是实的:运行镜像里不需要 uv、不需要 Poetry、不需要 pyproject,只需要 pip 和一把锁。镜像里少一套工具链,攻击面和体积都小一圈。
这里有个细节值得单独拎出来:运行阶段 COPY --from=locker /app/pylock.toml 只拷锁文件,不拷 requirements.txt。交接的唯一凭证就是这把锁。反过来想:如果锁文件里没记全(比如构建依赖、私有索引配置),运行阶段就会在你最不想看到的时候报错。锁文件交接的前提,是你确认过它自包含------这也是前面坑六(安装选项不进锁)要在生产前想清楚的原因。
横向对比:它不是来取代 requirements.txt 的,至少现在不是
很多人第一次听说 pylock.toml,第一反应是"requirements.txt 终于能退休了"。先看表,再下结论。
| requirements.txt | pylock.toml(PEP 751) | uv.lock | poetry.lock | |
|---|---|---|---|---|
| 是不是标准 | 不是,pip 约定俗成 | 是,PEP 751,2025-03-31 Final | 不是,uv 自有 | 不是,Poetry 自有 |
| 版本钉死 | 靠手写 ==,不强制 |
强制精确版本 | 强制精确版本 | 强制精确版本 |
| 文件哈希 | 可选 --hash,默认没有 |
强制,每个文件必带 | 有 | 有 |
| 安装时解析 | 要解析 | 不解析,照单抓药 | 不解析 | 不解析 |
| 跨平台/多 Python | 只对生成环境有效 | 格式支持多环境,pip 写锁目前只锁当前环境 | 支持多平台解析 | 支持多平台解析 |
| extras/依赖组 | 靠多个文件拆 | 格式支持,pip/uv 导出目前不写 | 支持 | 支持(组) |
| 安装选项(index、约束) | 能写 --index-url、-r 引用 |
不支持,PEP 明确排除 | 在 pyproject 里 | 在 pyproject 里 |
| 谁能读 | pip | 任何按 PEP 751 写的工具 | uv 为主 | Poetry 为主 |
| 状态(2026-11-17) | 一直能用 | pip 两侧都还是实验性 | 稳定 | 稳定 |
读这张表要抓住三行。第一行"是不是标准":pylock.toml 唯一的护城河就是"标准"两个字------Dependabot、云厂商、审计工具这些不愿意给每个包管理器单独适配的人,只认标准。第二行"安装选项":requirements.txt 能干的事,pylock.toml 有一半干不了。--index-url、引用别的 -r 文件、环境变量、私有索引配置,这些 PEP 明确排除在外。你的项目如果靠这些活着,锁文件现在还接不住。第三行"状态":pip 两侧都还挂着 experimental 的牌子,警告原文是"It may be removed/changed in a future release without prior warning"。标准 Final 了,实现还在实验期,这个反差就是 2026 年底 pylock.toml 的真实位置。
表里没放 pip-tools,是因为它和 pylock.toml 的关系最值得单独说一句。pip-compile 干的事和 pip lock 高度重合:把范围解析成精确版本,输出一份带哈希的 requirements.txt。区别在两点:第一,pip-tools 的输出还是 requirements.txt 格式,哈希是可选项(--generate-hashes 才加),而且装的时候照样要过一遍解析器;pylock.toml 的哈希是强制的,装的时候不解析。第二,pip-tools 的输出只有 pip 能读,pylock.toml 理论上谁都能读。所以如果你今天已经在用 pip-tools,迁到 pylock.toml 的收益不是"更能钉死版本"(pip-tools 本来就能),而是"钉死的结果能交给别人"------交给 Docker、交给云厂商、交给审计工具。只在自己机器上用的话,pip-tools 现在反而更顺手:它支持 --upgrade-package 单包升级,pip lock 还没有。
决策表再直接一点:
| 你的情况 | 建议 |
|---|---|
| 只要 pip,项目小,想钉死版本 | 现在就能用:pip lock -r requirements.txt + 提交 pylock.toml,CI 里装锁 |
| 用 uv/Poetry 做主力开发 | 别动主锁;把 pylock.toml 当导出物,只在需要交给 pip/云厂商/审计时才导出 |
| 需要一份锁、多种装法(生产/测试/文档) | 今天只有手写多用途锁,或者等写锁工具支持 marker;别指望 uv 导出能帮你分 |
| 部署在多平台(Linux + macOS + Windows) | 别用 pip 的锁直接上生产,pip 只锁当前平台;用 uv/PDM 的跨平台导出,或者等 pip 补多环境支持 |
| 私有索引、复杂安装选项 | 继续用 requirements.txt,pylock.toml 现在接不住这些 |
局限与坑:今天早上踩到的,一个一个说
这篇的坑不是从文档里抄的,是今天早上一个一个撞出来的。每个坑后面都跟绕法。
坑一:pip lock . 锁出来的文件,pip 自己装不上。 文章开头那段报错就是它。pip lock . 会把项目本身以 [packages.directory] path = "." 记进锁,安装时 pip 要对这个 file:// 要求校验哈希,目录没法校验,直接报错。绕法:写锁别锁项目本身,锁 requirements(pip lock -r requirements.txt),或者锁具体的包名(pip lock requests click)。项目本身的安装,继续用 pip install -e .,别走锁文件。
坑二:[web] 写了等于没写。 上面实测过:uv 导出的扁平锁,pip install -r 'pylock.all.toml[web]' 把 31 个包全装了,pytest、mkdocs 都进了生产环境,而且没有任何警告告诉你选择器没生效。绕法:在用 [extra] 或 --group 之前,先打开锁文件确认文件头有没有 extras / dependency-groups、包上有没有 marker。没有这两样,就当它是一份单用途锁,别写选择器。更稳妥的办法是装完跑 pip list | grep -E 'pytest|mkdocs' 之类的检查,确认没多装。
坑三:手写多用途锁,闭包差一个包就全军覆没。 我拼那份手写锁时,第一版漏了 anyio 依赖的 typing-extensions,第二版又漏了 httpx 依赖的 anyio,两次都栽在同一句报错上:
ERROR: In --require-hashes mode, all requirements must have their versions pinned with ==. These do not:
typing_extensions>=4.16.0 from https://.../typing_extensions-4.16.0-py3-none-any.whl (from anyio==4.16.0->pylock.multi.toml)
读锁安装默认开 --require-hashes,pip 会检查每个包的元数据里声明的依赖是不是也在锁里钉死了版本。差一个,整个安装失败------不是跳过、不是警告,是失败。绕法:手写锁之前,先拿一份工具导出的全量锁当"包清单"对照,或者用 pip install --dry-run 先验一遍。还有一个连带教训:第一次手写时我漏标了 colorama 的 marker(它是 pytest 的依赖),结果默认安装把它也装上了------marker 覆盖不全,依赖就会漏进默认集。
坑四:pip 的锁只对当前 Python 版本和当前平台有效。 pip lock 的帮助里白纸黑字写着:"The generated lock file is only guaranteed to be valid for the current python version and platform." 我今天的锁是在 Python 3.12.3 + Linux x86_64 上生成的,charset-normalizer 锁的是 cp312-manylinux 的 wheel。拿到 Python 3.13 或 macOS 上,这份锁要么装不上,要么装错 wheel。多平台项目现在别指望 pip 的锁,uv 的导出是跨平台解析的,拿它当多平台的交接件更靠谱。
坑五:实验性警告不是摆设。 每次读 pylock.toml,pip 都会打一行:
WARNING: Using pylock.toml as a requirements source is an experimental feature. It may be removed/changed in a future release without prior warning.
标准 Final 不等于实现稳定。写锁和装锁的命令名、行为,在 pip 25.1 到 26.3 之间已经变过好几轮(26.3 的 --group 语法、26.2 的 upload-time 都是后来补的)。生产流程里接进来之前,先想好"万一 27.x 改了行为,我的 CI 会不会炸",留好回退到 requirements.txt 的路。
坑六:锁文件不管构建依赖,也不管安装选项。 PEP 明确排除了两样东西:一是 sdist 的构建依赖(build requirements)不锁,二是 requirements.txt 里的安装选项(--index-url、--constraint、-r 引用、环境变量)不进锁。你的项目如果从私有索引装包、或者构建时要拉特定版本的 setuptools,这些信息还得放在别处,锁文件里找不到。别以为提交一份 pylock.toml 就等于"环境完全复现"了,它只复现安装那一步。
坑七:pip lock --requirements-from-script 在 26.3 上是坏的。 PEP 723 的单文件脚本(文件头里写 # /// script 声明依赖)本来也能锁,pip lock --help 里明明白白列着这个选项。我今天拿一个只有 requests>=2.31 的脚本实测,pip 26.3 直接抛出一串 traceback,根上是:
File ".../pip/_internal/cli/cmdoptions.py", line 908, in make_target_python
platforms=options.platforms,
AttributeError: 'Values' object has no attribute 'platforms'
命令没生成任何文件。这就是实验性功能的另一面:帮助里有的功能,不一定真能跑。单文件脚本的锁,先别用 pip lock 这条路,uv 的 uv run --with 或者先把依赖抽到 requirements 再锁,更稳当。这个 bug 我记在这里,pip 修了之后这段就过时了------你读到的时候可以自己跑一遍验证。
别和 PEP 735 搞混:一个管声明,一个管锁定
这篇的选题预告里特意交代过,要和 2026-11-09 写过的 PEP 735 划清界限,因为它俩长得太像了:都和 pyproject.toml 里的依赖组有关,都带"lock"这个词的联想。分工其实一句话就能说清------735 管"声明要装哪组",751 管"装的那组到底锁成了什么"。
PEP 735(依赖组,dependency groups)解决的是声明问题:以前测试依赖、文档依赖只能各写一个 requirements 文件,或者塞进 [project.optional-dependencies] 冒充 extra。735 给了它们一个正式位置:pyproject.toml 里的 [dependency-groups] 表,test = ["pytest>=8.0"] 这种写法从此有了标准含义,pip 25.1、Poetry 2.2、Hatch 1.16 在 2025 年内陆续跟进。
PEP 751 解决的是锁定问题:不管你用 extra 还是依赖组声明"要什么",最后安装的那一刻,到底装了哪个版本、哪个文件、哈希是多少,记在哪?751 答:记在 pylock.toml 里。
所以它俩是上下游,不是替代品。一个项目可以同时用:pyproject 里用 735 声明"test 组是 pytest",锁文件里用 751 记"这次锁的 pytest 是 9.2.0,wheel 地址和哈希是这些"。反过来,只用 735 不用 751,你每次安装还是要重新解析,版本照样可能漂;只用 751 不用 735,你声明依赖组的时候还得回到老办法。11 月 9 日那篇讲的是"怎么把依赖分组说清楚",这篇讲的是"分组说清楚之后,怎么把装的东西钉死"。
怎么选,下一步干什么
写到这里,结论其实已经摊开了。pylock.toml 不是"requirements.txt 的替代品",它是 Python 打包生态里第一次有了一个各方都认的"交接格式":写锁的工具可以各写各的,装锁的一方不用再学每种格式。标准定了,实现还在爬坡------pip 两侧实验性、写锁单用途、extras 选择要看锁文件脸色。这三句话,就是 2026 年 11 月 17 日的现状。
给不同的人三条下一步:
- 只用 pip 的个人项目/小团队 :今天就能试。
pip install -U pip到 26.3,pip lock -r requirements.txt生成锁,提交进仓库,CI 里改成pip install -r pylock.toml。成本是一条命令,收益是部署不再被解析结果晃点。记住别锁项目本身(坑一),装完核对一次pip list。 - uv/Poetry 用户 :主锁别动。需要把环境交给 pip、Docker、云厂商或者审计的时候,
uv export --format pylock.toml导一份当交接件;导出之前想清楚:导出的是一份扁平全量锁,[extra]选不中任何东西,生产和测试依赖会一起进去,介意的话先拆。 - 想写多用途锁的人 :先等一等,或者手写。手写之前把 PEP 751 里 marker 那一节读一遍,
'web' in extras这种集合语法写错一个引号,pip 的报错不会直接告诉你"marker 写错了"。手写完务必在三个空 venv 里把默认、[extra]、--group各装一遍,数包数------我今天就是这么验出来的。
如果你决定动手,一份按顺序来的迁移清单:
- 先把 pip 升到 26.3:
python -m pip install -U pip,确认pip --version是 26.3,26.1 之前没有从锁安装,26.3 之前没有[extra]和--group。 - 在项目根目录跑
pip lock -r requirements.txt,别跑pip lock .(坑一)。 - 打开生成的 pylock.toml,扫一眼:包的数量对不对、有没有你不认识的包、是不是全是当前平台的 wheel(坑四)。
- 在一个全新空 venv 里
pip install -r pylock.toml,装完pip list逐个核对版本。 - 把 requirements.txt 和 pylock.toml 成对提交;CI 里把安装命令换成装锁,顺手接个
pylock-lint之类的静态检查。 - 以后每次改依赖:改 requirements → 重锁 → 审 diff → 提交。diff 里出现说不上来由的包,先查再合。
快答:写之前最可能问的五个问题
锁文件要不要提交进仓库? 要。不提交的锁文件等于没锁------CI 和同事都看不到它。但要成对提交:requirements.txt(输入)和 pylock.toml(输出)一起进。只交锁不交输入,三个月后没人知道这把锁是怎么来的;只交输入不交锁,等于回到解析结果随缘的时代。顺带说一句,.gitignore 里别把 pylock.toml 当成构建产物忽略掉,它是源码的一部分,和 requirements.txt 一个待遇。
多个 Python 版本怎么办? 今天 pip 的锁是单 Python 的,一份锁只保一个版本。项目要同时支持 3.12 和 3.13,要么锁两份(pylock.py312.toml、pylock.py313.toml,文件名格式本身就支持多份),要么用 uv 的导出------它一个包能列多个 Python 版本的 wheel。选哪种,看你团队里谁负责写锁。
私有包、内部索引怎么办? 格式上有 packages.index 字段,能记包是从哪个索引来的;但安装选项(--index-url、认证配置)不进锁(坑六)。私有包现在能锁、能装,前提是安装那台机器自己配好了索引地址和凭证。锁文件不替你保管这些。
锁文件能当 SBOM(软件物料清单)用吗? 能当一半。它有精确版本、文件地址、哈希、上传时间,审计要的核心字段基本齐了;缺的那一半是构建依赖(不锁)和依赖关系边(pip/uv 导出目前不写 [[packages.dependencies]])。合规审计如果只要求"生产环境装了什么",它够用;如果要求"完整的依赖图谱",还得配别的工具。
现在上生产是不是太早? 看你怎么定义"上生产"。当成"部署的唯一依据",早了------两侧都还挂着实验性警告,pip lock --requirements-from-script 这种帮助里列着的功能今天实测都是坏的。当成"本地开发 + CI 的辅助钉死手段",不早,成本是一条命令,出了问题回退到 requirements.txt 只需要改一行 CI 配置。我的建议是:先在非关键项目上跑一个月,踩一遍坑一到坑七,再决定要不要推广。
最后留一个问题给你,也是这篇文章的讨论钩子:你的项目现在提交进仓库的到底是 requirements.txt、uv.lock,还是已经试过 pylock.toml?如果试过,你在哪个环节卡住的------是写锁、装锁,还是 extras 选不中?
参考资料
- PEP 751 -- A file format to record Python dependencies for installation reproducibility,Brett Cannon,Status: Final,Resolution 2025-03-31,Replaces PEP 665。https://peps.python.org/pep-0751/
- pip Changelog 26.3(2026-11-02):
-r pylock.toml[extra](#14205)、--group pylock.toml:docs(#14390)、--no-binary支持(#14187)。26.2(2026-07-29):upload-time、--only-final。26.1(2026-04-26):实验性pip install -r pylock.toml(#13876)。https://pip.pypa.io/en/stable/news/ - Poetry 2.3.0 发布公告(2026-01-18):poetry-plugin-export 1.10.0+ 可导出 pylock.toml,尚不能替代 poetry.lock。https://python-poetry.org/blog/announcing-poetry-2.3.0/
- pydevtools《What is PEP 751?》(2026-10-19 更新版):各工具采纳情况,PDM 可直接以 pylock.toml 为主锁,Poetry 截至 2026-04 未发布支持(本文以 Poetry 官方 2.3.0 公告为准,已更新该口径)。https://pydevtools.com/handbook/explanation/what-is-pep-751/
- 本地实测:Python 3.12.3、pip 26.3、uv 0.13.8,2026-11-17 当天在隔离 venv 中运行,命令与输出均为原文;手写多用途锁的数据取自 uv 0.13.8 导出的 pylock.toml。