Supported package managers¶

migrate-to-uv supports multiple package managers. By default, it tries to auto-detect the package manager based on the files (and their content) used by the package managers it supports. If you need to enforce a specific package manager to be used, use --package-manager.

Poetry¶

Note

migrate-to-uv supports migrating both projects that use Poetry-specific syntax for defining project metadata, and projects that use PEP 621, added in Poetry 2.0.

All existing Poetry metadata should be converted to uv when performing the migration:

Project metadata (name, version, authors, ...)
Dependencies and dependency groups (PyPI, path, git, URL)
Dependency extras (also known as optional dependencies)
Dependency sources
Dependency markers (including python and platform)
Multiple constraints dependencies
Package distribution metadata (packages, include and exclude)
Supported Python versions
Scripts and plugins (also known as entry points)

Version definitions set for dependencies are also preserved, and converted to their equivalent PEP 440 format used by uv, even for Poetry-specific version specification (e.g., caret (^) and tilde (~)).

Unsupported version specifiers¶

Although migrate-to-uv is able to migrate most Poetry-specific version specifiers to PEP 440 format, some specific features of Poetry versioning cannot be migrated, either because there are no equivalent in PEP 440, or because some cases are too complex to handle. In both cases, migrate-to-uv will fail the migration.

This section lists the features that are known to not be supported, and helps you find what to do to actually be able to perform the migration. If a case that migrate-to-uv was not able to handle is not listed here, feel free to create an issue on the GitHub repository.

"||" operator¶

Poetry allows defining multiple versions constraints using a double-pipe ("||") (or the equivalent pipe ("|")), that acts as an "or" operator, like this:

[tool.poetry.dependencies]
pytest = "^7.0||^8.0||^9.0"

Since PEP 440 does not provide any way to define an "or" operator, usage of this operator in versions will lead to a migration failure. You will need to manually update the syntax to not rely on this operator before attempting the migration.

In the simple example above, this one should be equivalent:

[tool.poetry.dependencies]
pytest = ">=7.0,<10"

For cases where specifiers are non-contiguous, you might want to only keep the highest version, e.g.:

[tool.poetry.dependencies]
pytest = "^7.0||^9.0"

could be transformed to:

[tool.poetry.dependencies]
pytest = "^9.0"

Note that non-contiguous versions that use "or" operator only work on projects that are not distributed as packages (since packages need to follow PEP 440 versioning).

Whitespace-separated specifiers¶

Similarly to PEP 440, Poetry allows defining multiple versions constraints using a comma (","), that acts as an "and" operator, like this:

[tool.poetry.dependencies]
pytest = "^8.4,!=8.4.2"

While this one is supported by migrate-to-uv, Poetry also allows using a whitespace (" ") instead of a comma (which is equivalent), like this:

[tool.poetry.dependencies]
pytest = "^8.4 !=8.4.2"

Using whitespaces in place of commas for delimiting specifiers is not supported by migrate-to-uv, and will lead to a migration failure. You will need to manually update the syntax to use comma-delimited specifiers before attempting the migration.

Build backend¶

Although uv has its own build backend, it cannot express everything that Poetry supports. For this reason, migrate-to-uv prioritises using uv if the package distribution metadata is simple enough to use it, but uses Hatch otherwise. It is possible to explicitly choose a build backend by using --build-backend.

When converting the build backend to Hatch, migrate-to-uv migrates the following things:

Poetry packages and include to Hatch include
Poetry exclude to Hatch exclude

Note

Path rewriting, defined with to in packages for Poetry, is also migrated to Hatch by defining sources in wheel target.

Specificities¶

Python classifiers¶

When building distributions, Poetry automatically adds Python classifiers based on the Python versions allowed by python under [tool.poetry.dependencies]. Since uv does not, if migrate-to-uv detects that Poetry build backend is used, it will assume that the project is a package, and will add the classifiers in classifiers under [project] section, in order to not lose those classifiers after the migration.

For instance, this pyproject.toml:

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "foo"
version = "0.0.1"

[tool.poetry.dependencies]
python = ">=3.10"

would get converted to:

[build-system]
requires = ["uv_build"]
build-backend = "uv_build"

[project]
name = "foo"
version = "0.0.1"
requires-python = ">=3.10"
classifiers = [
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
]

Note

Python classifiers will not get automatically added if a classifiers key is already defined under [project] section, as Poetry does not add them in that specific case.

Pipenv¶

All existing Pipenv metadata should be converted to uv when performing the migration:

Dependencies and development dependencies (PyPI, path, git, URL)
Package category groups
Package indexes
Dependency markers
Supported Python versions

pip-tools¶

Most pip-tools metadata is converted to uv when performing the migration.

By default, migrate-to-uv will search for:

production dependencies in requirements.in
development dependencies in requirements-dev.in

If your project uses different file names, or defines production and/or development dependencies across multiple files, you can specify the names of the files using --requirements-file and --dev-requirements-file (both can be specified multiple times), for instance:

migrate-to-uv \
  --requirements-file requirements-prod.in \
  --dev-requirements-file requirements-dev.in \
  --dev-requirements-file requirements-docs.in

Missing features¶

Dependencies that do not follow PEP 508 specification are not yet handled
References to other requirement files (e.g., -r other-requirements.in) are not supported, but the requirements file can manually be set with --requirements-file or --dev-requirements-file
Index URLs are not yet migrated

pip¶

Most pip metadata is converted to uv when performing the migration.

By default, migrate-to-uv will search for:

production dependencies in requirements.txt
development dependencies in requirements-dev.txt

If your project uses different file names, or defines production and/or development dependencies across multiple files, you can specify the names of the files --requirements-file and --dev-requirements-file (both can be specified multiple times), for instance:

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

Missing features¶

Dependencies that do not follow PEP 508 specification are not yet handled
References to other requirement files (e.g., -r other-requirements.txt) are not supported, but the requirements file can manually be set with --requirements-file or --dev-requirements-file
Index URLs are not yet migrated