{"id":9942,"library":"migrate-to-uv","title":"Migrate to uv","description":"migrate-to-uv is a command-line tool designed to help users transition their Python projects from traditional package managers like Poetry, Pipenv, or pip to `uv`'s `pyproject.toml` format. It aims to automate the conversion of project metadata, dependencies, and build configurations to be compatible with `uv`. The current version is 0.12.0, with new releases occurring regularly, often weekly or bi-weekly, to introduce features and address bugs.","status":"active","version":"0.12.0","language":"en","source_language":"en","source_url":"https://github.com/osprey-oss/migrate-to-uv","tags":["uv","poetry","pipenv","package management","migration","pyproject.toml"],"install":[{"cmd":"pip install migrate-to-uv","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[],"quickstart":{"code":"# Create a dummy Poetry project\nmkdir my-poetry-project\ncd my-poetry-project\npoetry init -n # Initialize without interaction\npoetry add requests\npoetry add black --group dev\n\n# Migrate the project to uv's pyproject.toml format\nmigrate-to-uv\n\n# You can now remove poetry related files\nrm poetry.lock pyproject.toml\n\n# If you check pyproject.toml, it should be updated for uv\n# You can then install dependencies with uv\n# uv sync\n\n# And run with uv\n# uv run python -c \"import requests; print(requests.__version__)\"","lang":"bash","description":"This quickstart demonstrates migrating a simple Poetry project to be compatible with `uv`'s `pyproject.toml` standards. It sets up a basic Poetry project, adds some dependencies, and then uses `migrate-to-uv` to convert its configuration. After migration, you would typically use `uv sync` to install dependencies."},"warnings":[{"fix":"No direct fix needed, as this is an automated improvement. If you require a specific build backend (e.g., Hatch for complex cases), you can still explicitly set it with `--build-backend hatch`.","message":"Automatic selection of build backend changed. Previously, it might have always used Hatch or required explicit `--build-backend`. Now, `migrate-to-uv` automatically chooses between `uv` and `Hatch` build backends based on the complexity of your package distribution metadata.","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"If your project relies on specific dependency group behavior, explicitly set `--dependency-groups-strategy legacy` to revert to the pre-0.11.0 behavior, or use `--dependency-groups-strategy all` or `--dependency-groups-strategy explicit` as needed.","message":"When migrating Poetry or Pipenv dependency groups, the default strategy changed. It used to explicitly set all non-optional groups to `default-groups`. Now, if `--dependency-groups-strategy` is not set, it defaults to `default-groups = 'all'` unless optional groups are present, in which case it behaves like the old default.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"Carefully review the error messages provided by `migrate-to-uv`. These messages will highlight specific features or configurations in your project that are not directly convertible or have no equivalent in `uv`, requiring manual adjustment before retry.","message":"Migration now aborts on unrecoverable errors. Previously, `migrate-to-uv` would only warn about issues that could lead to behavior changes but still perform the migration. It now aborts if it cannot ensure a consistent migration without altering project behavior.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"If migration to `uv` build backend fails, try migrating without specifying the build backend (allowing `migrate-to-uv` to choose automatically, often defaulting to Hatch for complex cases), or explicitly choose `--build-backend hatch`.","message":"The `uv` build backend is less flexible than Poetry or Hatch. Migrating to `uv` build backend (especially if explicitly chosen with `--build-backend uv`) might be aborted if your Poetry configuration uses features not expressible in `uv`'s build backend.","severity":"gotcha","affected_versions":">=0.9.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure that your package directory (e.g., `src/my_package_name`) contains an `__init__.py` file. If your project is using implicit namespace packages, consider restructuring to explicit packages or using the Hatch backend which supports more flexible layouts.","cause":"When migrating a Poetry project with a `src/` layout to the `uv` build backend, `uv` expects a `__init__.py` file within the package directory for explicit package discovery. If this file is missing, the migration fails.","error":"Migration aborted: Missing __init__.py file in package directory `src/<package_name>`."},{"fix":"Examine the `pyproject.toml` or `poetry.lock` for the specified dependency. You may need to simplify the version constraint or manually adjust it after a partial migration to a format like `some-package = \">=1.0, <2.0\"` which is generally well-supported.","cause":"The tool encountered a dependency version constraint (e.g., `^1.0.0`, `~1.2`, `>=1.0, <2.0`, or more complex ranges) that it could not translate reliably or without ambiguity into `uv`'s supported `pyproject.toml` format.","error":"Migration aborted: Unhandled version specification for dependency `some-package`."},{"fix":"Install the package using pip: `pip install migrate-to-uv`. Ensure your Python scripts directory (e.g., `~/.local/bin` on Linux/macOS or `Scripts` folder in your Python installation on Windows) is included in your system's PATH environment variable.","cause":"The `migrate-to-uv` package has not been installed, or the directory where it's installed is not in your system's PATH.","error":"Command 'migrate-to-uv' not found"}]}