基础设施迁移指南 · 更新 2026-06-27

Python Toolchain Migration Checklist：uv、pip、Poetry、pip-tools、pyenv、pipx、CI、Private Indexes 与 Publishing

面向准备迁移到 uv 的 Python 团队：避免破坏 packaging、CI、private indexes、lockfiles、publishing 和 developer onboarding。

Python toolchain migration 如果只当成速度 benchmark，很容易失败。uv 可以让 installs 和 project workflows 更快，但团队仍需要 lockfiles、Python versions、tools、private indexes、editable installs、build backends、publishing、CI caches 和 onboarding policy。

这份 checklist 把 uv brief 和 Infrastructure Radar 转成迁移计划：比较 uv、pip、Poetry、pip-tools、pyenv、pipx 和 mise 的角色，并给出从一个 repo 到 docs/CI/fallback/lockfile ownership 的 staged rollout。

RepoDaily 判断

当 uv 能减少真实项目摩擦时再采用，而不只是因为它更快。迁移应分阶段：先 tool execution，再一个 application repo，再 CI，再 packaging/publishing。release 行为未验证前保留 pip 或 Poetry；跨语言 tool pinning 问题交给 mise，而不是让 uv 解决所有事。

RepoDaily smoke-test evidence：本地 Python 迁移 fixture

这不是 uv、pip、Poetry 或任何 package manager 的性能评测。RepoDaily 做了一个小型 stdlib-only Python project，用来检查迁移 checklist 是否保留 pyproject metadata、可重复 test command、compile checks、可用时的 uv-run execution，以及明确的 lockfile policy。

证据项	Smoke-test 结果	为什么重要	局限性
本地迁移 fixture	6/6 个本地 smoke-test steps 通过。	验证的是迁移 checklist 的机制，不是工具排名。	小型 stdlib-only project；没有压力测试 external dependency resolver。
pyproject metadata	Fixture 在 `pyproject.toml` 中明确保留 `requires-python` 和 CI test command。	迁移应该让 runtime 和 validation rules 更容易 audit，而不是藏在临时命令里。	不覆盖复杂 build backends 或 optional dependency groups。
Baseline command parity	`python -m compileall src` 与 `python -m unittest discover -s tests` 都通过。	切换 installer 或 runner 前，应先保留可重复 baseline。	只使用 unittest 和 stdlib code。
uv-run check	当前 workspace 可用 uv，且 `uv run` 使用显式 `PYTHONPATH` 成功执行同一组本地测试。	Checklist 应记录实际跑过什么，而不是暗示宽泛 benchmark。	不是速度测试；没有下载 packages。
Lockfile policy	uv run 后存在 lockfile，证据也明确说明 fixture 没有 external dependencies。	Lockfile 应作为 policy 和 review artifact 讨论，而不只是副作用。	没有测试 version conflict 或 private-index behavior。

这节应理解为 RepoDaily 对迁移 checklist 的 smoke test，不是 package manager 排名。
这个测试支持页面建议：迁移时要让 metadata、test commands、lockfile policy 和实际跑过的步骤保持可见。
这个结果刻意很窄：适合作为可复现 sanity check，不代表 resolver speed、private indexes、binary wheels 或 publishing 能力。

快速矩阵

现有工具	uv 迁移目标	什么时候保留	收集证据
pip + venv	用 `uv sync`、`uv add`、`uv run` 和 project-local virtualenvs	项目很小且没有 lockfile/reproducibility 问题	Clean checkout setup time、import parity、test output
pip-tools	用 `uv lock` 和 `uv.lock` 管理 dependency decisions	Requirements compilation policy 已成熟稳定	Lockfile diff、dependency update review、private-index behavior
Poetry	先评估 uv 的 project sync 和 lock behavior	Publishing/build workflow 依赖 Poetry-specific behavior	Build artifact、publish dry run、script behavior、dependency groups
pyenv	测试 `uv python install` 管理 project interpreters	团队已有稳定 pyenv workflows	Python install path、version pin、CI parity
pipx	用 `uvx` 或 `uv tool` 管理 developer CLI tools	Tool isolation 和 upgrade policy 已有效	Tool version、cache behavior、uninstall/upgrade path
mise	用 mise pin uv 和非 Python tools	Repo 是 Python-only 且 uv 覆盖 workflow	mise.toml review、CI parity、tool owner

迁移准备度评分卡

在修改官方 onboarding docs 前，先给 repository 打分。

准备区域	0 分	1 分	2 分	Reviewer 问题
Project shape	Packaging style 未知	已知 app/library 类型	App/library/tool workflows 已记录	这个 repo 到底 shipping 什么？
Dependency policy	无 lock/update rule	非正式规则	Lockfile ownership 和 update review 已定义	谁更新 dependencies，怎么更新？
CI parity	Local 和 CI 不同	部分一致	Clean CI 使用与 local docs 相同命令	新 runner 能复现 local setup 吗？
Private indexes	Auth/index behavior 未测试	仅手动测试	CI 和 local private index path 已测试	Credentials 如何安全注入？
Publishing	未测试	Build 能跑	Build 和 publish dry run 已验证	Release 时会坏在哪里？
Fallback plan	无 rollback	手动 notes	有文档化 fallback 和 migration branch	如果 uv 阻塞 release 怎么回退？

30 分钟 uv 迁移 Smoke Test

在打开真实 migration PR 前运行。

0–5 分钟：inventory

列出现有 Python 文件：pyproject、requirements、lockfiles、Python version files、CI setup 和 release scripts。

成功标准引入 uv 前，当前 workflow 可见。

5–12 分钟：local uv run

生成或检查 `uv.lock`，运行 `uv sync`，再运行 project test 或 smoke command。

成功标准Clean local environment 能跑核心 workflow。

12–18 分钟：edge checks

检查 optional dependencies、editable installs、private indexes、scripts 和 Python version constraints。

成功标准已命名迁移风险，而不是忽略。

18–24 分钟：CI plan

草拟 CI command change 和 cache/version pinning strategy。

成功标准CI 能匹配 README，不靠隐藏命令。

24–30 分钟：migration decision

决定 migrate、longer pilot、keep existing tool 或拆分 local/CI/release responsibilities。

成功标准下一步有 owner、scope 和 fallback path。

迁移决策流程

先分类 repository：application、library、CLI、notebook project、monorepo package 或 internal service。
从只读盘点开始：`pyproject.toml`、requirements files、lockfiles、Python version files、CI YAML、private index config 和 publishing scripts。
在 migration branch 里运行 uv，形成 clean setup path：`uv lock`、`uv sync`、`uv run`、tests 以及开发者需要的 tool execution。
在修改 README 前测试 private indexes、editable installs、optional dependencies、dependency groups、platform markers 和 build backends。
更新 CI 以匹配本地命令，并记录 cache behavior、installer version 和 fallback path。
最后再决定 uv 是替代 pip/venv/pip-tools/Poetry/pyenv/pipx，还是只作为可选 helper。

场景表

场景	迁移模式	停止条件
小型内部 application	一次 clean test run 后采用 uv 管 lock、sync、run 和 CI	Private dependencies 或 deployment image 破坏
发布到外部的 Python library	本地测试 uv，但替换 release docs 前验证 build/publish dry run	Wheel/sdist metadata 或 publish path 和当前 policy 不同
Data science notebook repo	用 uv 管 environment sync 和 tool execution，明确 data/source notes	Notebook outputs 依赖 unmanaged local state
Polyglot product repo	用 mise pin uv、Node 和其他 tools；uv 管 Python dependencies	CI 和 local setup 变成两个 source of truth
Poetry-heavy project	在 branch 里 pilot uv；publishing 未验证前保留 Poetry release path	Scripts、dependency groups 或 build backend assumptions 破坏
Legacy requirements repo	生成 uv lock，并比较 imports/tests 后再移除 requirements files	Dependency resolution 改变行为且 reviewer 无法解释原因
团队范围 rollout	按 repo 迁移，保留 migration notes 和 fallback path	Docs 写 uv 但 CI/deploy 仍用旧 workflow

迁移风险清单

Speed-only adoption

更快 install 不够；迁移必须改善 local setup、CI、lockfile review 和 release confidence。

Publishing surprise

Applications 和 libraries 需求不同。替换 release tool 前必须验证 build 和 publish dry run。

Private index drift

Authentication、extra indexes、internal packages 和 caching 在 local 与 CI 中可能表现不同。

Mixed workflow limbo

如果 docs 用 uv、CI 用 pip、release 用 Poetry、developers 手动 pyenv，迁移只是多了一层。

Lockfile ownership gap

Lockfile 只有在 reviewers 知道谁能更新、如何 review diff、如何处理 security updates 时才有价值。

Tool execution trust

`uvx` 和 `uv tool` 很方便，但 unreviewed tools 不应变成 release-critical automation。

迁移实施模式

Tool execution first

在修改 application dependency workflows 前，先用 `uvx` 或 `uv tool` pilot developer-only CLIs。

One repository branch

创建一个 migration branch，同时修改 lockfile、README、CI 和 fallback notes。

CI mirrors README

README 里的命令应匹配 CI setup/test commands，否则 onboarding 证据很弱。

Release path exception

Published libraries 在 uv build/publish 行为验证前，保留 Poetry 或现有 release scripts。

mise pins the tools

当 repo 需要 pin uv、Node、Terraform、cloud CLIs 或其他非 Python tools 时用 mise。

Migration report

记录旧 workflow、新 workflow、已测命令、失败、fallback path、owner 和 next review date。

常见问题

给评估 uv 迁移的 Python 团队提供简短答案。

uv 应该立刻替代 Poetry 吗？

不一定。先 pilot uv 的 sync 和 CI，再验证 build/publish behavior，最后再改 published package 的 release path。

每个 library 都应该提交 `uv.lock` 吗？

取决于团队 policy。Applications 通常更受益于 committed lockfiles；libraries 可能采用不同规则。迁移前先写清楚。

mise 和 uv 怎么分工？

mise 负责 pin uv、Python、Node、Terraform 和其他 tools；uv 负责 Python dependency/project behavior。

第一步安全迁移是什么？

在一个低风险 application branch 使用 uv，跑 sync/tests/CI，记录 fallback，在 release 风险验证前保留旧 workflow。

来源

Feedback

这页是否帮助你做出决定？

匿名反馈只用于判断内容是否真正有用。

报告过期或缺失的证据