Configuration¶

Project path¶

By default, migrate-to-uv uses the current directory to search for the project to migrate. If the project is in a different path, you can set the path to a directory as a positional argument.

Example:

# Relative path
migrate-to-uv subdirectory

# Absolute path
migrate-to-uv /home/foo/project

Arguments¶

migrate-to-uv provides a few arguments to let you customize how the migration is performed.

--dry-run¶

Run the migration without modifying the files, printing the changes that would have been made in the terminal instead.

Example:

migrate-to-uv --dry-run

--skip-lock¶

By default, migrate-to-uv locks dependencies with uv lock at the end of the migration. This flag disables this behavior.

Example:

migrate-to-uv --skip-lock

--skip-uv-checks¶

By default, migrate-to-uv will exit early if a project already uses uv. This flag disables this behavior, allowing migrate-to-uv to run on a pyproject.toml that already has uv configured.

Note that the project must also have a valid non-uv package manager configured, otherwise it will fail to generate the uv configuration.

Example:

migrate-to-uv --skip-uv-checks

--ignore-locked-versions¶

By default, when locking dependencies with uv lock, migrate-to-uv keeps dependencies to the versions they were locked to with the previous package manager, if it supports lock files, and if a lock file is found. This behavior can be disabled, in which case dependencies will be locked to the highest possible versions allowed by the dependencies constraints.

Example:

migrate-to-uv --ignore-locked-versions

--replace-project-section¶

By default, existing data in [project] section of pyproject.toml is preserved when migrating. This flag allows completely replacing existing content.

Example:

migrate-to-uv --replace-project-section

--package-manager¶

By default, migrate-to-uv tries to auto-detect the package manager based on the files (and their content) used by the package managers it supports. If auto-detection does not work in some cases, or if you prefer to explicitly specify the package manager, you can explicitly set it.

Available options:

• pip
• pip-tools
• pipenv
• poetry

Example:

migrate-to-uv --package-manager poetry

--build-backend¶

The build backend to choose when performing the migration. If the option is not provided, the build backend will be automatically chosen based on the package distribution complexity, using uv if it is simple enough, or using Hatch otherwise.

Available options:

• hatch
• uv

Example:

migrate-to-uv --build-backend uv

--dependency-groups-strategy¶

Most package managers that support dependency groups install dependencies from all groups when performing installation. By default, uv will only install dev one.

In order to match the current package manager as closely as possible, migrate-to-uv sets all dependency groups (except the ones that could be optional, like Poetry allows to do) in default-groups under [tool.uv] section. If the only dependency group is dev, default-groups is not set, as uv already defaults to including only dev group.

If the default behavior is not suitable, it is possible to change it.

Available options:

• set-default-groups (default): Move each dependency group to its corresponding uv dependency group, and add all non-optional dependency groups in default-groups under [tool.uv] section (unless the only dependency group is dev one, as this is already uv's default)
• include-in-dev: Move each dependency group to its corresponding uv dependency group, and reference all non-optional dependency groups (others than dev one) in dev dependency group by using { include-group = "<group>" }
• keep-existing: Move each dependency group to its corresponding uv dependency group, without any further action
• merge-into-dev: Merge dependencies from all non-optional dependency groups into dev dependency group (optional dependency groups are moved to their corresponding uv dependency groups)

Example:

migrate-to-uv --dependency-groups-strategy include-in-dev

--requirements-file¶

Names of the production requirements files to look for, for projects using pip or pip-tools. The argument can be set multiple times, if there are multiple files.

Example:

migrate-to-uv --requirements-file requirements.txt --requirements-file more-requirements.txt

--dev-requirements-file¶

Names of the development requirements files to look for, for projects using pip or pip-tools. The argument can be set multiple times, if there are multiple files.

Example:

migrate-to-uv --dev-requirements-file requirements-dev.txt --dev-requirements-file requirements-docs.txt

--keep-current-build-backend¶

Keep the current build backend during the migration. This can be useful if the build backend cannot be expressed with any of the supported build backends (Hatch and uv), if you prefer to migrate it yourself, or if you want to stay on the current build backend.

When using Poetry (which is the only package manager where this setting applies), this will:

• leave [build-system] section untouched
• keep packages and include/exclude keys from [tool.poetry] section

Example:

migrate-to-uv --keep-current-build-backend

--keep-current-data¶

Keep the current package manager data (lock file, sections in pyproject.toml, ...) after the migration, if you want to handle the cleaning yourself, or want to compare the differences first.

Example:

migrate-to-uv --keep-current-data