FWIW here's a small poetry -> uv migration guide that should get most people started. I do realize it's not good enough to slap in the docs. There are a couple of problems: it depends on pdm, dependencies of dependencies can change, the locking script I attach is far from perfect/complete and requires manual edits afterwards.

First, you need to convert your poetry compatible pyproject.toml to be compatible with uv. You can actually do it quite easily with pdm (originally suggested here).

uvx pdm import pyproject.toml
Remove all poetry sections in the pyproject (i.e. [tool.poetry...] sections)
Replace

[tool.pdm.dev-dependencies]
dev = [

with

[tool.uv]
dev-dependencies = [

Done. Your pyproject.toml file is now compatible with UV and you can do uv lock or uv sync.

Having said that, it is likely that UV will resolve completely different versions of packages than what you already had in your poetry.lock. That doesn't have to be a problem, but can. It was a problem in my case.

To work around this, I used a small script to hardcode all the minor/patch versions of my packages in pyproject.toml before converting to uv compatible format. Then, after conversion, I would create the uv.lock with uv lock. Then, I'd undo the hardcoded versions in the original pyproject.toml and convert again. Because uv by default will prefer versions from the lock, you now have all your versions pinned as they were in poetry and mostly the same packages in the lock (dependencies of dependencies can be different). It should be safe to do uv sync without worrying about things breaking due to versions change.

Below is the script I used to hardcode minor/patch versions in pyproject.toml. It's not perfect and will create incorrect results for dependencies with extras/from git etc. but these are easy to tweak manually.

from pathlib import Path

import toml

# Load poetry.lock and pyproject.toml
lockfile_path = Path("poetry.lock")
pyproject_path = Path("pyproject.toml")

# Parse the lock file
with lockfile_path.open("r") as lockfile:
    lock_data = toml.load(lockfile)

# Parse pyproject.toml
with pyproject_path.open("r") as pyproject_file:
    pyproject_data = toml.load(pyproject_file)

# Build a map of package names to their specific versions from poetry.lock
locked_versions = {package["name"]: package["version"] for package in lock_data["package"]}


# Helper function to update dependencies in a given section
def update_dependencies(dependencies):
    for dep_name, dep_constraint in dependencies.items():
        if dep_name in locked_versions:
            dependencies[dep_name] = locked_versions[dep_name]
            print(f"Updated {dep_name} to version {locked_versions[dep_name]}")
        else:
            print(f"{dep_name} not found in poetry.lock, skipping.")


# Update dependencies in pyproject.toml
update_dependencies(pyproject_data["tool"]["poetry"]["dependencies"])
update_dependencies(pyproject_data["tool"]["poetry"]["group"]["dev"]["dependencies"])

# Write the updated pyproject.toml
with pyproject_path.open("w") as pyproject_file:
    toml.dump(pyproject_data, pyproject_file)

print("pyproject.toml has been updated with specific versions.")

Uh oh!

Write migration guides #5200

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions