Migrate to uv

Common errors

• Migration aborted: Missing __init__.py file in package directory `src/<package_name>`.

  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.
  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.

• Migration aborted: Unhandled version specification for dependency `some-package`.

  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.
  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.

• Command 'migrate-to-uv' not found

  cause The `migrate-to-uv` package has not been installed, or the directory where it's installed is not in your system's PATH.
  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.

Warnings

• breaking 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.
  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`.
• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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`.

Install

• pip install migrate-to-uv Install with pip

Quickstart

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.

# Create a dummy Poetry project
mkdir my-poetry-project
cd my-poetry-project
poetry init -n # Initialize without interaction
poetry add requests
poetry add black --group dev

# Migrate the project to uv's pyproject.toml format
migrate-to-uv

# You can now remove poetry related files
rm poetry.lock pyproject.toml

# If you check pyproject.toml, it should be updated for uv
# You can then install dependencies with uv
# uv sync

# And run with uv
# uv run python -c "import requests; print(requests.__version__)"