Back↩︎

Migration guide from Poetry to UV

uv is a simple and fast tool inspired by Poetry that helps you manage Python project dependencies.

UV installation

Follow the instructions in the official documentation.

I recommend using the curl approach:

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

Migrating pyproject.toml file to be UV compatible

To convert the pyproject.toml file to a nearly compatible format with uv, you can use pdm:

uvx pdm import pyproject.toml

After running the command, remove the following sections from pyproject.toml:

• poetry related sections like tool.poetry, including their child sections
• build-system section
• tool.pdm section and its child sections

Next, adjust the PyPI source configuration if present. Rename [[tool.pdm.source]] to [[tool.uv.index]].

Optionally, you can rearrange sections for better readability. I recommend moving the [project] section to the top.

Validation

Install all dependencies from the pyproject.toml file. uv will automatically create a virtual environment, so remove any existing virtual environments beforehand.

uv sync

To exclude development dependencies, use the --no-dev flag:

uv sync --no-dev

At this point, your project should be working with uv.

You can now remove following files and directories:

• poetry.lock
• .pdm-build

Next steps

Update the following as needed:

• Dockerfile
• CI/CD pipeline

For a complete example of a Python project using uv, check out my repository: hello-python