用 uv 替换掉 pip 和 poetry：我把 6 个老仓库都迁过去了

最近重装开发环境，新机器拉一个 requirements.txt 装 30 分钟，老机器上 Python 版本一升级 pip 就报错。我受够了，试试 uv——Astral 出的那套工具，和 ruff 一个团队。跑了半个月，把手头 6 个老 Python 项目全部迁完。这篇聊下我为什么换、怎么迁、有哪些坑。

先上结论：uv 不只是 pip 加速器，它把 venv、依赖锁定、Python 版本管理、打包发布全都接了，速度比 pip 快一个数量级。requirements.txt 能直接跑，迁移成本几乎为零。

装：

bash
curl -LsSf https://astral.sh/uv/install.sh | sh

不用 sudo，命令直接可用。

单文件脚本：扔掉 requirements.txt

原来一个脚本要 requirements.txt + venv 两步，现在一条命令搞定：

bash
uv init myscript --script
uv add requests rich
uv run myscript.py

--script 会自动生成带 PEP 723 元数据的单文件脚本，依赖跟着脚本走，发给别人直接能跑。临时搞个抓数据的小工具再也不需要 venv 目录了。

项目：替换 poetry / pipenv

我老项目里 poetry.lock 经常跟 pyproject.toml 不一致，CI 上 reinstall 必报。迁到 uv 之后：

bash
uv init
uv add fastapi 'uvicorn[standard]'
uv add --dev pytest ruff mypy
uv lock
uv sync

lock 文件叫 uv.lock，比 poetry.lock 小三分之一，解析速度快得多。我一个项目 200 多个依赖，poetry install 要 3 分钟，uv sync 18 秒，差距肉眼可见。

Python 版本：再也不用 pyenv 了

这块是最大惊喜。uv 自动装 Python，要哪个版本直接：

bash
uv python install 3.12
uv python pin 3.12

pin 之后项目里所有 uv run 都用 3.12，不用手动 activate venv，也不用 pyenv。CI 里直接 pip install uv && uv sync，连 setup-python action 都省了。

工具运行：临时试 ruff 不污染 venv

bash
uvx ruff check .
uvx mypy src/

uvx 等于临时建个 venv 装包跑完即删，比 pipx 快很多。我现在所有 linter/formatter 都用 uvx 跑。

---

踩坑也有几个，记下来。

系统 Python 包被破坏过。第一次跑 uv tool install 装全局命令，结果跟系统 pip 冲突，apt 装的 python3-requests 被覆盖了。教训是开发环境彻底切到 uv，系统级包不要混。

lockfile 跨平台。uv 默认锁定当前平台，团队里 macOS 和 Linux 互相 sync 会少包。要跨平台就 uv lock --upgrade 或者显式指定 --index。

Docker 镜像里 uv 还是新东西。之前 RUN pip install -r requirements.txt 要换成 RUN uv sync --frozen --no-dev，COPY lock 文件和 pyproject.toml 进去，分层缓存才生效。

老 wheel 装不上。极少数公司内网私有源没预编译包，下载源码编译要 5 分钟。临时方案是 UV_INDEX_URL 指向官方 PyPI，或者提前在基础镜像里 uv pip install。

编辑器补全。PyCharm 老版本对 uv venv 识别有 bug，要选 “Show virtual environments at first”；VSCode 配合 Pylance 直接认 .venv/bin/python，没遇到过问题。

最后说一句：uv 现在就是 Python 依赖管理的默认选择，没什么好犹豫的。pip 也不是不能用，但慢、乱、不可复现。迁移成本主要在 CI 和 Dockerfile，跑一遍就完了。