uv Project Migration

uv 项目迁移

Purpose

迁移目的

Migrate existing Python projects to uv from pip, Poetry, Pipenv, or Conda. Transfer all dependencies, preserve development configurations, validate functionality, and roll out changes to your team.

将现有Python项目从pip、Poetry、Pipenv或Conda迁移至uv。迁移所有依赖项、保留开发配置、验证功能，并向团队推广变更。

Quick Start

快速开始

Convert an existing project to uv in three commands:

bash

undefined

只需三条命令即可将现有项目转换为uv项目：

bash

undefined

From pip/requirements.txt project

从pip/requirements.txt项目迁移

cd my-legacy-project uv init --requirements requirements.txt

From Poetry project

从Poetry项目迁移

cd my-poetry-project uv init --pyproject

Verify everything works

验证所有功能正常

uv run pytest


Your project now uses uv with all original dependencies preserved.

uv run pytest


你的项目现在已使用uv，且所有原始依赖项均已保留。

Instructions

详细步骤

Step 1: Understanding When and Why to Migrate

步骤1：了解迁移的时机与原因

Benefits of migrating to uv:

10-100x faster dependency resolution
Simpler syntax than Poetry or Pipenv
Single tool replaces pip, poetry, pipenv, virtualenv
Better lock file format
Excellent cross-platform support

When to migrate:

Legacy pip + requirements.txt projects
Poetry projects wanting better performance
Pipenv projects needing simplified tooling
Teams standardizing on one package manager

When to NOT migrate:

Projects with complex Poetry features (build backends)
Legacy Conda-dependent projects
Projects with platform-specific wheels

迁移至uv的优势：

依赖解析速度提升10-100倍
语法比Poetry或Pipenv更简洁
单一工具替代pip、poetry、pipenv、virtualenv
更优的锁文件格式
出色的跨平台支持

适合迁移的场景：

基于pip + requirements.txt的遗留项目
希望获得更好性能的Poetry项目
需要简化工具链的Pipenv项目
希望统一包管理器的团队

不适合迁移的场景：

使用复杂Poetry特性（如构建后端）的项目
严重依赖Conda的遗留项目
包含平台特定whl包的项目

Step 2: Prepare Your Existing Project

步骤2：准备现有项目

For pip/requirements.txt projects:

bash

cd my-project
ls -la

针对pip/requirements.txt项目：

bash

cd my-project
ls -la

Should have: requirements.txt, src/, tests/, setup.py or pyproject.toml

应包含：requirements.txt、src/、tests/、setup.py或pyproject.toml


**For Poetry projects:**
```bash
cd my-poetry-project
cat pyproject.toml | head -20


**针对Poetry项目：**
```bash
cd my-poetry-project
cat pyproject.toml | head -20

Should have: [tool.poetry] section with name, version, dependencies

应包含：[tool.poetry] section，包含name、version、dependencies


**For Pipenv projects:**
```bash
cd my-pipenv-project
ls -la


**针对Pipenv项目：**
```bash
cd my-pipenv-project
ls -la

Should have: Pipfile, Pipfile.lock

应包含：Pipfile、Pipfile.lock


**Backup your project:**
```bash
git add .
git commit -m "Backup before uv migration"
git branch backup-pre-uv-migration


**备份项目：**
```bash
git add .
git commit -m "Backup before uv migration"
git branch backup-pre-uv-migration

Step 3: Automatic requirements.txt Conversion

步骤3：自动转换requirements.txt

For pip projects with requirements.txt:

bash

undefined

针对使用requirements.txt的pip项目：

bash

undefined

Navigate to project

进入项目目录

cd my-project

Initialize uv with existing requirements

基于现有requirements初始化uv

uv init --requirements requirements.txt

This creates:

此命令将创建：

- pyproject.toml (from requirements.txt)

- pyproject.toml（从requirements.txt生成）

- .python-version (from current Python)

- .python-version（基于当前Python版本）

- uv.lock (resolved lock file)

- uv.lock（已解析的锁文件）


**Verify pyproject.toml was created:**
```bash
cat pyproject.toml


**验证pyproject.toml是否创建成功：**
```bash
cat pyproject.toml

Should contain all your dependencies from requirements.txt

应包含requirements.txt中的所有依赖项


**Complex requirements files:**
```bash


**处理复杂的requirements文件：**
```bash

If you have multiple requirements files

若存在多个requirements文件

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

undefined

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

undefined

Step 4: Migrate from Poetry

步骤4：从Poetry迁移

For Poetry projects (pyproject.toml):

bash

cd my-poetry-project

针对使用pyproject.toml的Poetry项目：

bash

cd my-poetry-project

Option A: Automatic conversion

选项A：自动转换

uv init --pyproject


**If automatic fails, manual conversion:**

```bash

uv init --pyproject


**若自动转换失败，手动转换步骤：**

```bash

1. Create uv project

1. 创建uv项目

uv init

2. Copy dependencies from Poetry to uv

2. 将Poetry依赖复制到uv

Edit pyproject.toml:

编辑pyproject.toml：

Change [tool.poetry] section → [project] section

将[tool.poetry] section 改为 [project] section

Change "poetry" dependencies format → standard format

将Poetry依赖格式转换为标准格式

Before (Poetry):

转换前（Poetry格式）：

[tool.poetry.dependencies] python = "^3.11" fastapi = "^0.104.0"

After (uv/standard):

转换后（uv/标准格式）：

[project] requires-python = ">=3.11" dependencies = [ "fastapi>=0.104.0,<1.0.0", ]

3. Add Poetry dev dependencies as uv groups

3. 将Poetry开发依赖添加为uv分组

[dependency-groups] dev = [ "pytest>=8.0.0", "black>=23.0.0", ]


**Resolve dependencies:**
```bash
uv sync --all-groups

[dependency-groups] dev = [ "pytest>=8.0.0", "black>=23.0.0", ]


**解析依赖：**
```bash
uv sync --all-groups

Step 5: Migrate from Pipenv

步骤5：从Pipenv迁移

For Pipenv projects (Pipfile/Pipfile.lock):

bash

cd my-pipenv-project

针对使用Pipfile/Pipfile.lock的Pipenv项目：

bash

cd my-pipenv-project

1. Read Pipfile to understand structure

1. 查看Pipfile结构

cat Pipfile

2. Create uv project

2. 创建uv项目

uv init

3. Convert Pipfile to pyproject.toml

3. 将Pipfile转换为pyproject.toml

Edit pyproject.toml following this pattern:

按照以下模式编辑pyproject.toml：

From Pipfile:

Pipfile中的内容：

[packages] django = ">=3.2" requests = "~=2.31.0"

[dev-packages] pytest = "" black = ""

[packages] django = ">=3.2" requests = "~=2.31.0"

[dev-packages] pytest = "" black = ""

To pyproject.toml:

转换为pyproject.toml：

[project] dependencies = [ "django>=3.2", "requests>=2.31.0,<2.32.0", ]

[dependency-groups] dev = [ "pytest", "black", ]


**Resolve dependencies:**
```bash
uv sync --all-groups

[project] dependencies = [ "django>=3.2", "requests>=2.31.0,<2.32.0", ]

[dependency-groups] dev = [ "pytest", "black", ]


**解析依赖：**
```bash
uv sync --all-groups

Step 6: Testing and Validation

步骤6：测试与验证

Verify migration worked:

bash

undefined

验证迁移是否成功：

bash

undefined

Check dependencies resolved

检查依赖是否解析完成

uv tree

Run existing tests

运行现有测试

uv run pytest

Run linting/type-checking if applicable

若有需要，运行代码检查/类型检查

uv run mypy src/ uv run ruff check src/

Run application if applicable

若有需要，运行应用

uv run python -m myapp


**Compare lock files (if migrating from Poetry/Pipenv):**

```bash

uv run python -m myapp


**对比锁文件（从Poetry/Pipenv迁移时）：**

```bash

List dependencies from uv

导出uv的依赖列表

uv tree > /tmp/uv-deps.txt

Compare counts

对比依赖数量

wc -l /tmp/uv-deps.txt

Should be similar to old package manager

应与旧包管理器的依赖数量相近


**Performance comparison:**

```bash


**性能对比：**

```bash

Original tool (e.g., poetry)

原工具（如poetry）

time poetry install

New tool (uv)

新工具（uv）

time uv sync

uv should be significantly faster

uv的速度应显著更快

undefined

undefined

Step 7: Team Onboarding and Rollout

步骤7：团队培训与推广

Prepare team documentation:

bash

undefined

准备团队文档：

bash

undefined

Create MIGRATION_GUIDE.md or update README.md

创建MIGRATION_GUIDE.md或更新README.md

Include:

文档应包含：

1. Why we're migrating

1. 迁移的原因

2. What changed (commands, workflow)

2. 变更内容（命令、工作流）

3. Installation instructions

3. 安装说明

4. Common troubleshooting

4. 常见问题排查


**Update project documentation:**

```markdown


**更新项目文档：**

```markdown

Installation and Setup

安装与配置

Prerequisites

前置要求

uv installed:

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

已安装uv：

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

Setup Development Environment

配置开发环境

bash

cd project-directory
uv sync --all-groups      # Install all dependencies
uv run pytest             # Run tests

bash

cd project-directory
uv sync --all-groups      # 安装所有依赖
uv run pytest             # 运行测试

Commands Changed

命令变更对照表

Old Command	New Command	Notes
poetry install	uv sync	No equivalent needed
poetry add requests	uv add requests	Simpler syntax
poetry run pytest	uv run pytest	Shorter prefix
pipenv install	uv sync	Automatic resolution
pip install -r requirements.txt	uv sync	All in pyproject.toml


**Rollout strategy:**

```bash

旧命令	新命令	说明
poetry install	uv sync	无额外参数需求
poetry add requests	uv add requests	语法更简洁
poetry run pytest	uv run pytest	前缀更短
pipenv install	uv sync	自动解析依赖
pip install -r requirements.txt	uv sync	所有依赖统一在pyproject.toml中管理


**推广策略：**

```bash

Step 1: Merge migration to main branch

步骤1：将迁移代码合并至主分支

git add pyproject.toml uv.lock git commit -m "Migrate project to uv package manager" git push

Step 2: Team pulls and verifies

步骤2：团队成员拉取代码并验证

git pull uv sync --all-groups uv run pytest # Verify tests pass

git pull uv sync --all-groups uv run pytest # 验证测试通过

Step 3: Update CI/CD pipelines

步骤3：更新CI/CD流水线

(See uv-ci-cd-integration skill for details)

（详情请查看uv-ci-cd-integration技能）

Step 4: Optional: Remove old tool files

步骤4：可选：移除旧工具文件

rm requirements.txt # If migrating from pip rm Pipfile Pipfile.lock # If migrating from Pipenv git add -A git commit -m "Remove old package manager files"

undefined

rm requirements.txt # 从pip迁移时 rm Pipfile Pipfile.lock # 从Pipenv迁移时 git add -A git commit -m "Remove old package manager files"

undefined

Examples

示例

Example 1: Migrate Simple pip Project

示例1：迁移简单pip项目

bash

undefined

bash

undefined

Original project structure

原始项目结构

ls -la

pyproject.toml (minimal)

pyproject.toml（基础版）

requirements.txt (your dependencies)

requirements.txt（依赖文件）

src/

tests/

Migrate

迁移

cd ~/my-project uv init --requirements requirements.txt

Verify

验证

cat pyproject.toml uv tree

Test

测试

uv run pytest

Commit

提交代码

git add . git commit -m "Migrate to uv"

undefined

git add . git commit -m "Migrate to uv"

undefined

Example 2: Migrate Poetry Project to uv

示例2：从Poetry项目迁移至uv

bash

undefined

bash

undefined

Original Poetry project

原始Poetry项目

cd ~/poetry-project cat pyproject.toml | grep -A 10 "[tool.poetry]"

Migrate (automatic)

迁移（自动方式）

uv init --pyproject

If automatic fails, manual steps:

若自动失败，执行手动步骤：

Edit pyproject.toml to convert [tool.poetry] → [project]

编辑pyproject.toml，将[tool.poetry]转换为[project]

Ensure all dependencies are listed correctly

确保所有依赖项正确列出

Verify migration

验证迁移结果

uv sync --all-groups uv tree uv run pytest

undefined

uv sync --all-groups uv tree uv run pytest

undefined

Example 3: Migrate Pipenv Project

示例3：从Pipenv项目迁移

bash

undefined

bash

undefined

Original Pipenv project

原始Pipenv项目

cd ~/pipenv-project cat Pipfile

Convert Pipfile → pyproject.toml manually

手动将Pipfile转换为pyproject.toml

Edit Pipfile, copy/transform dependencies

编辑Pipfile，复制并转换依赖项

Create uv project

创建uv项目

uv init

Edit pyproject.toml with converted dependencies

编辑pyproject.toml，添加转换后的依赖项

Run

执行

uv sync --all-groups

Verify

验证

uv tree uv run pytest

undefined

uv tree uv run pytest

undefined

Example 4: Multi-Stage Migration with Testing

示例4：分阶段迁移与测试

bash

undefined

bash

undefined

Step 1: Create feature branch

步骤1：创建特性分支

git checkout -b feature/migrate-to-uv

Step 2: Setup uv

步骤2：配置uv

uv init --requirements requirements.txt

Step 3: Validate thoroughly

步骤3：全面验证

uv sync --all-groups uv run pytest uv run mypy src/ uv run ruff check src/

Step 4: Check for differences

步骤4：检查差异

uv tree

Compare with original project structure

与原始项目结构对比

Step 5: Commit and PR

步骤5：提交并创建PR

git add pyproject.toml uv.lock git commit -m "chore: migrate to uv package manager" git push origin feature/migrate-to-uv

Step 6: After merge, notify team

步骤6：合并后通知团队

- Update README.md with new commands

- 更新README.md中的新命令

- Create documentation for team setup

创建团队配置文档

- Remove old requirement files after validation

验证通过后移除旧依赖文件

undefined

undefined

Example 5: Rollback if Issues Found

示例5：迁移失败时回滚

bash

undefined

bash

undefined

If migration has problems, rollback

若迁移出现问题，执行回滚

git checkout main git reset --hard HEAD~1 # Undo last commit

git checkout main git reset --hard HEAD~1 # 撤销最后一次提交

Or restore from backup branch

或从备份分支恢复

git checkout backup-pre-uv-migration

Debug the issue

排查问题

- Check pyproject.toml for syntax errors

- 检查pyproject.toml的语法错误

- Verify all dependencies listed

- 验证所有依赖项是否已列出

- Try uv sync --all-groups again

- 重新执行uv sync --all-groups

undefined

undefined

Example 6: Monorepo Migration

示例6：单体仓库迁移

bash

undefined

bash

undefined

Monorepo structure

单体仓库结构

ls -la

project-a/

project-b/

shared-lib/

Migrate project-a

迁移project-a

cd project-a uv init --requirements requirements.txt

Add shared library as path dependency

添加共享库作为路径依赖

uv add --editable ../shared-lib

Migrate project-b

迁移project-b

cd ../project-b uv init --requirements requirements.txt

Add shared library

添加共享库

uv add --editable ../shared-lib

Sync everything

同步所有依赖

cd .. uv sync --all-groups

undefined

cd .. uv sync --all-groups

undefined

Requirements

前置要求

uv installed (install:

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

)

Existing Python project with dependencies (pip, Poetry, Pipenv, or Conda)
Git repository (recommended for backup/rollback)
Python 3.8+ available
Access to package index (PyPI) during migration

已安装uv（安装命令：

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

）

现有Python项目，包含依赖（基于pip、Poetry、Pipenv或Conda）
Git仓库（推荐用于备份/回滚）
Python 3.8+ 可用
迁移过程中可访问包索引（PyPI）

uv-project-migration

Original

Translation

uv Project Migration

uv 项目迁移

Purpose

迁移目的

Quick Start

快速开始

From pip/requirements.txt project

从pip/requirements.txt项目迁移

From Poetry project

从Poetry项目迁移

Verify everything works

验证所有功能正常

Instructions

详细步骤

Step 1: Understanding When and Why to Migrate

步骤1：了解迁移的时机与原因

Step 2: Prepare Your Existing Project

步骤2：准备现有项目

Should have: requirements.txt, src/, tests/, setup.py or pyproject.toml

应包含：requirements.txt、src/、tests/、setup.py或pyproject.toml

Should have: [tool.poetry] section with name, version, dependencies

应包含：[tool.poetry] section，包含name、version、dependencies

Should have: Pipfile, Pipfile.lock

应包含：Pipfile、Pipfile.lock

Step 3: Automatic requirements.txt Conversion

步骤3：自动转换requirements.txt

Navigate to project

进入项目目录

Initialize uv with existing requirements

基于现有requirements初始化uv

This creates:

此命令将创建：

- pyproject.toml (from requirements.txt)

- pyproject.toml（从requirements.txt生成）

- .python-version (from current Python)

- .python-version（基于当前Python版本）

- uv.lock (resolved lock file)

- uv.lock（已解析的锁文件）

Should contain all your dependencies from requirements.txt

应包含requirements.txt中的所有依赖项

If you have multiple requirements files

若存在多个requirements文件

Step 4: Migrate from Poetry

步骤4：从Poetry迁移

Option A: Automatic conversion

选项A：自动转换

1. Create uv project

1. 创建uv项目

2. Copy dependencies from Poetry to uv

2. 将Poetry依赖复制到uv

Edit pyproject.toml:

编辑pyproject.toml：

Change [tool.poetry] section → [project] section

将[tool.poetry] section 改为 [project] section

Change "poetry" dependencies format → standard format

将Poetry依赖格式转换为标准格式

Before (Poetry):

转换前（Poetry格式）：

After (uv/standard):

转换后（uv/标准格式）：

3. Add Poetry dev dependencies as uv groups

3. 将Poetry开发依赖添加为uv分组

Step 5: Migrate from Pipenv

步骤5：从Pipenv迁移

1. Read Pipfile to understand structure

1. 查看Pipfile结构

2. Create uv project

2. 创建uv项目

3. Convert Pipfile to pyproject.toml

3. 将Pipfile转换为pyproject.toml

Edit pyproject.toml following this pattern:

按照以下模式编辑pyproject.toml：

From Pipfile:

Pipfile中的内容：

To pyproject.toml:

转换为pyproject.toml：

Step 6: Testing and Validation