Port from Poetry to uv

[johnthagen]

Given the funding and momentum behind uv, it seems inevitable that it will become the most powerful, de facto packaging tool for Python. When it is deemed ready, it should be recommended in place of Poetry.

Benefits

• Bootstrapping: A source of friction with Poetry is that users must first be instructed on how to install Python and pipx before they can install Poetry
• uv can install Python itself, which is totally outside the scope of Poetry and is a desirable feature in and of itself (i.e. rustup for Python)
  • Poetry is adding this feature too
    • Can install the right Python version like PDM and UV do python-poetry/poetry#9905
    • feat(cli): introduce python management commands python-poetry/poetry#10112
• Speed: uv, being written in Rust and also having a design focus on performance, will likely out perform Poetry on every benchmark
• Single binary: uv is distributed as a single binary meaning that all, among other things, users of uv version X get the exact same code. On the other hand, Poetry does not pin its dependencies so breakages can occur and not all users are guarenteed to have the same third party libraries installed with it
  • Ship Poetry releases with pinned dependencies python-poetry/poetry#7990
• uv supports MUSL natively, so it can install natively on MUSL-based operating systems like Alpine, which is used in some container images
  • Poetry, on the other hand, depends on packages that may or may not have MUSL-wheels uploaded to PyPI
  • As of Poetry 2.2.1, Poetry no longer seems to exhibit this problem and all of it dependencies can install into into alpine containers directly
• uv supports running scripts with PEP 723 Inline script metadata, while it does not appear Poetry supports this. pipx would need to be used for this, which further fragments the tools users must understand and keep up to date.
• uv does not respect requires-python upper bounds, which is very nice in practice
  • Poetry still enforces this upper bound: Remove upper bound checking on Python version python-poetry/poetry#10136
• uv can express required platforms for wheel coverage
  • Allow users to mark platforms as "required" for wheel coverage astral-sh/uv#10067

Upstream Requests

uv is still a fast moving project and it may be advantageous to wait to recommend moving to it until a few things have settled.

• Dependency groups PEP 735: This is a feature that Poetry has and uv only currently has support for a single "dev" group. It is nice to be able to break up dependencies into logical groups and provide support for installing them independently.
  • Support for PEP 735: Dependency Groups in pyproject.toml astral-sh/uv#8090
  • Note, Poetry does not support this either, but has it's own concept of dependency groups: Support PEP 735 – Dependency Groups in pyproject.toml python-poetry/poetry#9751
• PEP 751 standardized lockfiles: Like Poetry, uv has it's own custom lockfile format. There is on going discussions about creating a standardized lockfile format. If approved, it may be nice to wait until uv supports this, so that users do not have to migrate lockfiles twice (once to uv's custom format, and again to the standardized format).
  • https://discuss.python.org/t/pep-751-lock-files-again/
  • https://discuss.python.org/t/pep-751-one-last-time/77293
• uv.lock support in Nox
  • Support for uv.lock wntrblm/nox#841

Nice to Have

uv

• uv having it's own build backend
  • Add a uv build backend astral-sh/uv#3957
  • Poetry provides it's own build backend, and it's nice to not have to track two different projects to form the entire pipeline of build and packaging. In uv's case, currently one would have to track uv and hatchling.
• uv updating top level dependencies in pyproject.toml
  • (🎁) Add a command to "upgrade" dependency constraints in the pyproject.toml astral-sh/uv#6794
• uv supporting private projects
  • Private Projects astral-sh/uv#8214
  • Note, Poetry does not support this either: Implement private projects python-poetry/poetry#1537
• uv check similar to poetry check
  • Add uv check command to validate pyproject.toml uv configuration astral-sh/uv#9653
• uv equivalent to Poetry package-mode
  • Add a non-package-mode astral-sh/uv#10204
• uv sync install all dependancy groups by default
  • Better default for uv sync astral-sh/uv#10934

Nox

• Nox supports installing dependency groups
  • Enable reading dependency specifiers from PEP 621 pyproject.toml wntrblm/nox#845
  • Note: nox-poetry does not have this either
    • Support installing Poetry dependency groups cjolowicz/nox-poetry#663

PyCharm

• Native PyCharm support: PyCharm already automatically supports the .venv virtual environments created, but it would be even better if it supported introspecting uv.lock and provided features similar to its native Poetry integration
  • https://youtrack.jetbrains.com/issue/PY-70533/Support-package-management-via-uv
  • https://www.jetbrains.com/pycharm/whatsnew/2024-3-2/

Dependabot

• Dependabot support for uv.lock
  • Support updating uv.lock dependabot/dependabot-core#10478
  • Python: Support PEP 735 [dependency-groups] in pyproject.toml dependabot/dependabot-core#10847
  • Note: Dependabot supports Poetry lockfiles

Migration Guide

• poetry sync -> uv sync
• Lockfile freshness: uv lock --check
  • Reframe --locked and --frozen as --check operations for uv lock astral-sh/uv#9662
• Remove tool.poetry.dependencies.python upper bound that is required by Poetry
  • Ignore upper-bounds on Requires-Python astral-sh/uv#4086
• tool.poetry.group -> [dependency-groups]
  • https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-groups
• poetry update - > uv lock --upgrade
• [tool.poetry.dependencies.python] -> .python-version file
  • https://docs.astral.sh/uv/concepts/python-versions/#python-version-files
• Add [tool.uv.default-groups] as uv does not install all groups by default
  • https://docs.astral.sh/uv/concepts/projects/dependencies/#default-groups
• Replace nox-poetry -> nox
• poetry show --tree -> uv tree
• poetry export -> uv export
• --only main -> --no-default-groups
• --no-root -> --no-install-project
• poetry build -> uv build
• --only -> --only-group

Other changes

python-blueprint/.dockerignore

Line 8 in 35be74f

!poetry.lock

[johnthagen]

uv 0.5.0 had a lot of breaking changes

• https://github.com/astral-sh/uv/releases/tag/0.5.0

So it's probably still prudent to continue to let it settle in while it goes through it's rapid early development.

[drmikehenry]

There's nothing wrong with waiting for some dust to settle, but the items marked "Breaking changes" in the 0.5.0 release notes don't seem very destabilizing to me. Because they potentially "could break some workflows", they've been gathered into a new 0.x.0 release, but these changes "have been marked as breaking out of an abundance of caution. We expect most users to be able to upgrade without making changes."

Also interesting is this issue and associated pull request that's in review:

• Should uv graduate from 'beta' on PyPI? astral-sh/uv#8941
• Update uv development status classifier to "Stable" on PyPI astral-sh/uv#8943

When the pull request lands, uv will be marked with the classifier "Development Status :: 5 - Production/Stable".

So Astral may soon be considering uv to be stable.

[benomahony]

Looks like this has landed!

[johnthagen]

Dependabot support looks to have landed in a broken state, so will want the dust to settle on that

• Support updating uv.lock dependabot/dependabot-core#10478 (comment)
• Inconsistent version for wheel in lockfile updated by Dependabot astral-sh/uv#12254