How to migrate from Poetry to uv

This guide walks through the process of migrating a Poetry-managed Python project to uv using the migrate-to-uv tool.

Prerequisites

• uv installed
• A Poetry-managed Python project

Basic Migration

1. Navigate to your Poetry project directory:

   cd your-poetry-project

2. Run the migration tool:

   uvx migrate-to-uv

3. The tool will:

   • Convert your Poetry project metadata to uv format
   • Preserve dependency versions
   • Generate a uv.lock file
   • Keep dependency groups

Handling Common Issues

Dealing with Private Package Repositories

If your project uses private package indexes:

1. Set the appropriate environment variables:

   # If your Poetry config has:
   # [[tool.poetry.source]]
   # name = "company-repo"
   # url = "https://repo.example.com"
   
   # Set these variables:
   export UV_INDEX_COMPANY_REPO_USERNAME=<username>
   export UV_INDEX_COMPANY_REPO_PASSWORD=<password>
   
   # Then run the migration
   uvx migrate-to-uv

Managing Dependency Groups

Poetry’s dependency groups work differently from uv’s default behavior. Choose a strategy based on your workflow:

# Default: maintain all groups and configure them as default groups
uvx migrate-to-uv --dependency-groups-strategy set-default-groups

# Include all groups as references in the dev group
uvx migrate-to-uv --dependency-groups-strategy include-in-dev

# Move all dependencies into the dev group
uvx migrate-to-uv --dependency-groups-strategy merge-into-dev

# Keep groups without modifications
uvx migrate-to-uv --dependency-groups-strategy keep-existing

Testing the Migration Without Making Changes

To see what would change without modifying files:

uvx migrate-to-uv --dry-run

Skipping Lock File Generation

If you prefer to generate the lock file separately:

uvx migrate-to-uv --skip-lock

Preserving Poetry Configuration

To keep the original Poetry configuration for comparison:

uvx migrate-to-uv --keep-current-data

Verifying the Migration

After migration:

1. Inspect the generated pyproject.toml for correctness
2. Verify that dependency versions match your expectations
3. Check that the correct dependency groups were created
4. Ensure any path, git, or URL dependencies were properly migrated

Testing the Migrated Project

Test that your project works with uv:

# Install the project's dependencies
uv sync

# Run your project's tests
uv run pytest

Troubleshooting

• If auto-detection fails, specify Poetry explicitly:

  uvx migrate-to-uv --package-manager poetry

• If migrating a project that already has uv configuration:

  uvx migrate-to-uv --skip-uv-checks

• If you want to override an existing project section:

  uvx migrate-to-uv --replace-project-section