Skip to content

Add support for the package manager uv#362

Merged
edmorley merged 4 commits intomainfrom
uv-support
May 13, 2025
Merged

Add support for the package manager uv#362
edmorley merged 4 commits intomainfrom
uv-support

Conversation

@edmorley
Copy link
Member

@edmorley edmorley commented May 13, 2025

(This is the CNB equivalent of heroku/heroku-buildpack-python#1791)

Adds support for the package manager uv:
https://docs.astral.sh/uv/

...which has (very justifiably!) become extremely popular in the last year:

uv-star-history-2025-05-07

This specifically adds support for uv's project mode (uv sync), which uses a lockfile rather then a requirements.txt file: https://docs.astral.sh/uv/guides/projects/

(While uv does have a pip compatible mode that supports requirements files, using a lockfile is a best practice for deploying an app, and not using one means losing most of the benefits of using uv.)

Apps must have a pyproject.toml, uv.lock and .python-version file (all of which are created by default by uv init followed by either uv lock or any of the other commands that sync/update the lockfile).

We don't support omitting the .python-version file when using uv, since otherwise it leads to a much worse UX in several cases. (For example, when the buildpack default version differs from requires-python in the pyproject.toml file, particularly when requires-python happens to also match the distro Python in the underlying base image.)

The buildpack installs dependencies using uv sync --locked --no-default-groups, to ensure development/test dependencies are not installed.

We don't use --no-dev instead, since that only excludes the dev group, and some apps may be using other group names and have added them to uv's default-groups in pyproject.toml so that local development workflows work with a plain uv sync with no additional args. (PEP 735 doesn't actually prescribe recommended group names, and in fact uses test in its example rather than dev, so non-standard names may be common.)

For more on uv's dependency group behaviour, see:
https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-groups

uv is installed into a build-only layer, so is not available at run-time (since it's not typically needed at run-time and doing so reduces the image size). Both Python and the entrypoints of installed dependencies are available on PATH, so use of uv run is not required at run-time to use dependencies in the environment.

I've marked this semver: major since in the (probably unlikely) event there are projects using this CNB that have both a uv.lock and also either a requirements.txt or poetry.lock, then this change will cause their builds to error (until one of the files is deleted).

Closes #248.
GUS-W-17141085.


Note: This repository is for the Python CNB (Cloud Native Buildpack) used by Fir-generation apps on Heroku. For uv support for Cedar-Generation apps, see the classic Python buildpack's PR instead.

Adds support for the package manager uv:
https://docs.astral.sh/uv/

This specifically adds support for uv's project mode (`uv sync`), which
uses a lockfile rather then a `requirements.txt` file:
https://docs.astral.sh/uv/guides/projects/

(While uv does have a pip compatible mode that supports requirements
files, using a lockfile is a best practice for deploying an app, and not
using one means losing most of the benefits of using uv.)

Apps must have a `pyproject.toml`, `uv.lock` and `.python-version` file
(all of which are created by default by `uv init` followed by either
`uv lock` or any of the other commands that sync/update the lockfile).

We don't support omitting the `.python-version` file when using uv,
since otherwise it leads to a much worse UX in several cases. (For
example, when the buildpack default version differs from
`requires-python` in the `pyproject.toml` file, particularly when
`requires-python` happens to also match the distro Python in the
underlying base image.)

The buildpack installs dependencies using `uv sync --locked --no-default-groups`,
to ensure development/test dependencies are not installed.

We don't use `--no-dev` instead, since that only excludes the
`dev` group, and some apps may be using other group names and have added
them to uv's `default-groups` in `pyproject.toml` so that local
development workflows work with a plain `uv sync` with no additional
args. (PEP 735 doesn't actually prescribe recommended group names, and
in fact uses `test` in its example rather than `dev`, so non-standard
names may be common.)

For more on uv's dependency group behaviour, see:
https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-groups

uv is installed into a build-only layer, so is not available at
run-time (since it's not typically needed at run-time and doing so
reduces the image size). Both Python and the entrypoints of installed
dependencies are available on `PATH`, so use of `uv run` is not
required at run-time to use dependencies in the environment.

I've marked this `semver: major` since in the (probably unlikely) event
there are projects using this CNB that have both a `uv.lock` and also
either a `requirements.txt` or `poetry.lock`, then this change will
cause their builds to error (until one of the files is deleted).

Closes #248.
GUS-W-17141085.
@edmorley edmorley self-assigned this May 13, 2025
@edmorley edmorley added enhancement New feature or request semver: major labels May 13, 2025
@edmorley edmorley marked this pull request as ready for review May 13, 2025 15:59
@edmorley edmorley requested a review from a team as a code owner May 13, 2025 15:59
@edmorley edmorley enabled auto-merge (squash) May 13, 2025 19:42
@edmorley edmorley merged commit 562bc58 into main May 13, 2025
6 checks passed
@edmorley edmorley deleted the uv-support branch May 13, 2025 19:42
heroku-linguist bot added a commit that referenced this pull request May 13, 2025
## heroku/python

### Added

- Added support for the package manager uv. ([#362](#362))
@heroku-linguist heroku-linguist bot mentioned this pull request May 13, 2025
heroku-linguist bot added a commit that referenced this pull request May 13, 2025
## heroku/python

### Added

- Added support for the package manager uv. ([#362](#362))
heroku-linguist bot added a commit that referenced this pull request May 13, 2025
## heroku/python

### Added

- Added support for the package manager uv. ([#362](#362))

Co-authored-by: heroku-linguist[bot] <136119646+heroku-linguist[bot]@users.noreply.github.com>
heroku-linguist bot added a commit to heroku/cnb-builder-images that referenced this pull request May 13, 2025
## heroku/python

### Added

- Added support for the package manager uv. ([#362](heroku/buildpacks-python#362))
@edmorley edmorley linked an issue May 13, 2025 that may be closed by this pull request
@edmorley
Copy link
Member Author

edmorley commented May 13, 2025

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request semver: major

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support for uv, the Python package manager Support the uv package manager

2 participants