Add support for the package manager uv #1791
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Member
Author
|
Example of using this with the Python Getting Started guide repo (with a demo branch that has had it's |
colincasey
reviewed
May 7, 2025
colincasey
reviewed
May 7, 2025
Adds support for the package manager uv: https://docs.astral.sh/uv/ And specifically 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 `runtime.txt` (or omitting the `.python-version` file) when using uv, since otherwise it leads to a much worse UX in several cases. (For example, when the `runtime.txt` version or buildpack default version differs from `requires-python` in the `pyproject.toml` file. Or worse, when `requires-python` happens to match the distro Python in the underlying base image.) For now, if a `requirements.txt`, `Pipfile` or `poetry.lock` are found, they will take precedence over `uv.lock` for backwards compatibility (currently a warning is shown, but in the future this will become an error). This means users of the third-party `heroku-buildpack-uv` will need to remove that buildpack in order to use the new native uv support, since it exports a `requirements.txt` file during the build which will take precedence. For standard (non-Heroku CI) builds, 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 Heroku CI builds, the buildpack installs dependencies using `uv sync --locked`, which will install all default groups. See: https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-groups For now, we don't expose user provided env vars to `uv sync` (similar to the behaviour for other package managers), however, will start doing so as part of addressing #1451 and #1700. uv is installed into the build cache rather than the slug, so is not available at run-time (since it's not typically needed at run-time and doing so reduces the slug 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. Closes #1616. GUS-W-17310796.
Member
Author
|
Dev Center updates:
Changelog announcement: |
This was referenced Jun 12, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds support for the package manager uv:
https://docs.astral.sh/uv/
...which has (very justifiably!) become extremely popular in the last year:
This specifically adds support for uv's project mode (
uv sync), which uses a lockfile rather then arequirements.txtfile: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.lockand.python-versionfile (all of which are created by default byuv initfollowed by eitheruv lockor any of the other commands that sync/update the lockfile).We don't support
runtime.txt(or omitting the.python-versionfile) when using uv, since otherwise it leads to a much worse UX in several cases. (For example, when theruntime.txtversion or buildpack default version differs fromrequires-pythonin thepyproject.tomlfile, particularly whenrequires-pythonhappens to also match the distro Python in the underlying base image.)For now, if a
requirements.txt,Pipfileorpoetry.lockare found, they will take precedence overuv.lockfor backwards compatibility (currently a warning is shown, but in the future this will become an error). This means users of the third-party heroku-buildpack-uv will need to remove that buildpack in order to use the new native uv support, since it exports arequirements.txtfile during the build which will take precedence.For standard (non-CI) Heroku builds, the buildpack installs dependencies using
uv sync --locked --no-default-groups, to ensure development/test dependencies are not installed.We don't use
--no-devinstead, since that only excludes thedevgroup, and some apps may be using other group names and have added them to uv'sdefault-groupsinpyproject.tomlso that local development workflows work with a plainuv syncwith no additional args. (PEP 735 doesn't actually prescribe recommended group names, and in fact usestestin its example rather thandev, so non-standard names may be common.)For Heroku CI builds, the buildpack installs dependencies using
uv sync --locked, which will install all default groups.For more on uv's dependency group behaviour, see:
https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-groups
For now, we don't expose user provided env vars to
uv sync(similar to the behaviour for other package managers), however, will start doing so as part of addressing #1451 and #1700.uv is installed into the build cache rather than the slug, so is not available at run-time (since it's not typically needed at run-time and doing so reduces the slug size). Both Python and the entrypoints of installed dependencies are available on
PATH, so use ofuv runis not required at run-time to use dependencies in the environment.Closes #1616.
GUS-W-17310796.
Note: This repository is for the classic Python buildpack used by Cedar-generation apps on Heroku. For uv support for Fir-Generation apps, see the Python CNB's tracking issue instead.