# How to migrate from Poetry to uv

This guide walks through the process of migrating a [Poetry](https://pydevtools.com/handbook/reference/poetry.md)-managed Python project to [uv](https://pydevtools.com/handbook/reference/uv.md) using the [migrate-to-uv](https://osprey-oss.github.io/migrate-to-uv/) tool.

## Prerequisites

- [uv](https://docs.astral.sh/uv/) installed
- A [Poetry](https://pydevtools.com/handbook/reference/poetry.md)-managed Python project

## Basic Migration

### 1. Navigate to your Poetry project directory

```bash
cd your-poetry-project
```

### 2. Run the migration tool

```bash
uvx migrate-to-uv
```

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:

   ```bash
   # 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:

```bash
# 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:

```bash
uvx migrate-to-uv --dry-run
```

### Skipping Lockfile Generation

If you prefer to generate the lockfile separately:

```bash
uvx migrate-to-uv --skip-lock
```

### Preserving Poetry Configuration

To keep the original Poetry configuration for comparison:

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

## Verifying the Migration

{{< callout type="info" >}}
Always verify your migrated configuration, especially for packages intended for distribution. While `migrate-to-uv` aims to match Poetry's behavior, edge cases may require manual adjustments.
{{< /callout >}}

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:

```bash
# Install the project's dependencies
uv sync

# Run your project's tests
uv run pytest
```

## Troubleshooting

- If auto-detection fails, specify Poetry explicitly:
  ```bash
  uvx migrate-to-uv --package-manager poetry
  ```

- If migrating a project that already has uv configuration:
  ```bash
  uvx migrate-to-uv --skip-uv-checks
  ```

- If you want to override an existing project section:
  ```bash
  uvx migrate-to-uv --replace-project-section
  ```