pip项目怎么迁移到uv

目录

1. pip迁移到uv这一步正是 uv 最有价值的地方 👍 我按**“最小风险、可回退、工程化”的方式，给你一套标准迁移流程**。 目标是：不破坏现有 pip 项目，一步步引入 uv。
2. 一、迁移前你需要确认的东西（30 秒检查）
3. ✅ 情况 A（最常见）
4. ✅ 情况 B（稍现代）
5. ❌ 情况 C（老项目）
6. 👉 A / B 都很好迁，C 也能迁，只是多一步
7. 二、最安全迁移方案（推荐）
8. Step 1️⃣ 安装 uv（一次性）
9. Step 2️⃣ 用 uv 安装原有依赖（零侵入）
10. 三、引入虚拟环境自动管理（推荐做）
11. ✅ 不用 activate ✅ CI / 本地一致
12. 四、从 requirements.txt 迁移到 pyproject.toml（关键一步）
13. Step 4️⃣ 初始化 pyproject.toml（不会覆盖）
14. 如果已有 pyproject.toml，uv 会直接复用。
15. Step 5️⃣ 导入 requirements 依赖
16. Step 6️⃣ 验证运行
17. 五、迁移后建议删 / 保留哪些文件？
18. 六、Docker / CI 迁移（很多人卡在这）
19. 🔹 原来（pip）
20. 🔹 推荐（uv）
21. 七、常见坑（提前避雷）
22. ❗ 1. 本地 Python 版本不一致
23. ❗ 2. editable 安装（-e .）
24. ❗ 3. 私有源 / 镜像
25. 八、完整迁移 checklist（照着走）

pip迁移到uv这一步正是 uv 最有价值的地方 👍 我按**“最小风险、可回退、工程化”的方式，给你一套标准迁移流程**。 目标是：不破坏现有 pip 项目，一步步引入 uv。#

一、迁移前你需要确认的东西（30 秒检查）#

你的 pip 项目一般会是下面几种之一：

✅ 情况 A（最常见）#

project/
├─ requirements.txt
├─ requirements-dev.txt
├─ main.py

✅ 情况 B（稍现代）#

project/
├─ pyproject.toml
├─ requirements.txt

❌ 情况 C（老项目）#

setup.py
setup.cfg

👉 A / B 都很好迁，C 也能迁，只是多一步#

二、最安全迁移方案（推荐）#

先让 uv 接管安装，但不改任何代码

Step 1️⃣ 安装 uv（一次性）#

pip install uv
# 或
curl -Ls https://astral.sh/uv/install.sh | sh

验证：

uv --version

---

Step 2️⃣ 用 uv 安装原有依赖（零侵入）#

uv pip install -r requirements.txt

如果你有 dev 依赖：

uv pip install -r requirements-dev.txt

📌 此时：

• 项目结构 完全没变
• 只是 pip → uv pip
• 已经能感受到 速度提升 👉 这一步就可以停下来了（已经是收益点）

---

三、引入虚拟环境自动管理（推荐做）#

让 uv 接管 .venv，但仍然兼容 pip 项目结构

uv venv

会生成：

.venv/

之后所有命令都变成：

uv pip install -r requirements.txt
uv run python main.py

✅ 不用 activate ✅ CI / 本地一致#

四、从 requirements.txt 迁移到 pyproject.toml（关键一步）#

这一步才是真正“迁移到 uv 模式”

---

Step 4️⃣ 初始化 pyproject.toml（不会覆盖）#

uv init

如果已有 pyproject.toml，uv 会直接复用。#

Step 5️⃣ 导入 requirements 依赖#

uv add -r requirements.txt

如果你有 dev 依赖：

uv add -r requirements-dev.txt --dev

这一步会：

• 写入 pyproject.toml
• 生成 uv.lock 📌 此时项目结构会变成：

project/
├─ pyproject.toml
├─ uv.lock        ✅
├─ .venv/
├─ main.py

---

Step 6️⃣ 验证运行#

uv run python main.py

或：

uv run pytest

---

五、迁移后建议删 / 保留哪些文件？#

---

六、Docker / CI 迁移（很多人卡在这）#

🔹 原来（pip）#

RUN pip install -r requirements.txt

🔹 推荐（uv）#

RUN uv sync --frozen

或者最小改动：

RUN uv pip install -r requirements.txt

---

七、常见坑（提前避雷）#

❗ 1. 本地 Python 版本不一致#

uv python list
uv python install 3.12

然后在 pyproject.toml 里锁：

[project]
requires-python = ">=3.11,<3.13"

---

❗ 2. editable 安装（-e .）#

uv add --editable .

---

❗ 3. 私有源 / 镜像#

[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

---

八、完整迁移 checklist（照着走）#

• 安装 uv
• uv pip install -r requirements.txt
• uv venv
• uv init
• uv add -r requirements.txt
• 提交 pyproject.toml + uv.lock
• CI / Docker 改用 uv