Add support for the package manager uv

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
(in the future this will become a warning then 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.

Author: edmorley

.github/dependabot.yml

@@ -24,7 +24,9 @@ updates:
   - package-ecosystem: "pip"
     directory: "/"
     schedule:
-      interval: "monthly"
+      # We set this to a more frequent interval than the above since uv is still under rapid
+      # iteration, and we'll generally want to be on the latest version.
+      interval: "weekly"
     ignore:
       # We're not updating to setuptools v71+ due to its new approach to vendored dependencies:
       # https://github.com/heroku/heroku-buildpack-python/pull/1630#issuecomment-2324236653

.github/workflows/ci.yml

@@ -47,8 +47,8 @@ jobs:
       HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
       HEROKU_API_USER: ${{ secrets.HEROKU_API_USER }}
       HEROKU_DISABLE_AUTOUPDATE: 1
-      PARALLEL_SPLIT_TEST_PROCESSES: 75
-      RSPEC_RETRY_RETRY_COUNT: 2
+      PARALLEL_SPLIT_TEST_PROCESSES: 85
+      RSPEC_RETRY_RETRY_COUNT: 1
     steps:
       - name: Checkout
         uses: actions/checkout@v4

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Added support for the package manager uv. ([#1791](https://github.com/heroku/heroku-buildpack-python/pull/1791))
 
 ## [v284] - 2025-05-06
 

README.md

@@ -14,7 +14,7 @@ See the [Getting Started on Heroku with Python](https://devcenter.heroku.com/art
 
 ## Application Requirements
 
-A `requirements.txt`, `Pipfile` or `poetry.lock` file must be present in the root (top-level) directory of your app's source code.
+A `requirements.txt`, `Pipfile`, `poetry.lock`, or `uv.lock` file must be present in the root (top-level) directory of your app's source code.
 
 ## Configuration
 

bin/compile

@@ -31,6 +31,7 @@ source "${BUILDPACK_DIR}/lib/pipenv.sh"
 source "${BUILDPACK_DIR}/lib/poetry.sh"
 source "${BUILDPACK_DIR}/lib/python_version.sh"
 source "${BUILDPACK_DIR}/lib/python.sh"
+source "${BUILDPACK_DIR}/lib/uv.sh"
 
 compile_start_time=$(nowms)
 
@@ -180,6 +181,9 @@ case "${package_manager}" in
 	poetry)
 		poetry::install_poetry "${python_home}" "${python_major_version}" "${CACHE_DIR}" "${EXPORT_PATH}"
 		;;
+	uv)
+		uv::install_uv "${CACHE_DIR}" "${EXPORT_PATH}" "${python_home}"
+		;;
 	*)
 		utils::abort_internal_error "Unhandled package manager: ${package_manager}"
 		;;
@@ -189,8 +193,8 @@ meta_time "package_manager_install_duration" "${package_manager_install_start_ti
 # SQLite3 support.
 # Installs the sqlite3 dev headers and sqlite3 binary but not the
 # libsqlite3-0 library since that exists in the base image.
-# We skip this step on Python 3.13 or when using Poetry, as a first step towards removing this feature.
-if [[ "${python_major_version}" == +(3.9|3.10|3.11|3.12) && "${package_manager}" != "poetry" ]]; then
+# We skip this step on Python 3.13 or when using Poetry/uv, as a first step towards removing this feature.
+if [[ "${python_major_version}" == +(3.9|3.10|3.11|3.12) && "${package_manager}" != +(poetry|uv) ]]; then
 	install_sqlite_start_time=$(nowms)
 	source "${BUILDPACK_DIR}/bin/steps/sqlite3"
 	buildpack_sqlite3_install
@@ -209,6 +213,9 @@ case "${package_manager}" in
 	poetry)
 		poetry::install_dependencies
 		;;
+	uv)
+		uv::install_dependencies
+		;;
 	*)
 		utils::abort_internal_error "Unhandled package manager: ${package_manager}"
 		;;

bin/report

@@ -76,6 +76,7 @@ STRING_FIELDS=(
 	python_version_requested
 	python_version
 	setuptools_version
+	uv_version
 	wheel_version
 )
 
@@ -101,7 +102,6 @@ ALL_OTHER_FIELDS=(
 	setup_py_only
 	sqlite_install_duration
 	total_duration
-	uv_lockfile
 )
 
 for field in "${STRING_FIELDS[@]}"; do

lib/cache.sh

@@ -115,6 +115,14 @@ function cache::restore() {
 					cache_invalidation_reasons+=("The Poetry version has changed from ${cached_poetry_version:-"unknown"} to ${POETRY_VERSION}")
 				fi
 				;;
+			uv)
+				local cached_uv_version
+				cached_uv_version="$(meta_prev_get "uv_version")"
+				# uv support was added after the metadata store, so we'll always have the version here.
+				if [[ "${cached_uv_version}" != "${UV_VERSION:?}" ]]; then
+					cache_invalidation_reasons+=("The uv version has changed from ${cached_uv_version:-"unknown"} to ${UV_VERSION}")
+				fi
+				;;
 			*)
 				utils::abort_internal_error "Unhandled package manager: ${package_manager}"
 				;;
@@ -132,6 +140,7 @@ function cache::restore() {
 			"${cache_dir}/.heroku/python" \
 			"${cache_dir}/.heroku/python-poetry" \
 			"${cache_dir}/.heroku/python-stack" \
+			"${cache_dir}/.heroku/python-uv" \
 			"${cache_dir}/.heroku/python-version" \
 			"${cache_dir}/.heroku/requirements.txt"
 

lib/package_manager.sh

@@ -49,6 +49,11 @@ function package_manager::determine_package_manager() {
 		package_managers_found_display_text+=("poetry.lock (Poetry)")
 	fi
 
+	if [[ -f "${build_dir}/uv.lock" ]]; then
+		package_managers_found+=(uv)
+		package_managers_found_display_text+=("uv.lock (uv)")
+	fi
+
 	# TODO: Deprecate/sunset this fallback, since using setup.py declared dependencies is
 	# not a best practice, and we can only guess as to which package manager to use.
 	if ((${#package_managers_found[@]} == 0)) && [[ -f "${build_dir}/setup.py" ]]; then
@@ -59,10 +64,6 @@ function package_manager::determine_package_manager() {
 		meta_set "setup_py_only" "false"
 	fi
 
-	if [[ -f "${build_dir}/uv.lock" ]]; then
-		meta_set "uv_lockfile" "true"
-	fi
-
 	local num_package_managers_found=${#package_managers_found[@]}
 
 	case "${num_package_managers_found}" in
@@ -75,8 +76,8 @@ function package_manager::determine_package_manager() {
 				Error: Couldn't find any supported Python package manager files.
 
 				A Python app on Heroku must have either a 'requirements.txt',
-				'Pipfile' or 'poetry.lock' package manager file in the root
-				directory of its source code.
+				'Pipfile', 'poetry.lock' or 'uv.lock' package manager file in
+				the root directory of its source code.
 
 				Currently the root directory of your app contains:
 
@@ -93,10 +94,10 @@ function package_manager::determine_package_manager() {
 				Otherwise, add a package manager file to your app. If your app has
 				no dependencies, then create an empty 'requirements.txt' file.
 
-				If you would like to see support for the package manager uv,
-				please vote and comment on these GitHub issues:
-				https://github.com/heroku/heroku-buildpack-python/issues/1616
-				https://github.com/heroku/roadmap/issues/323
+				If you aren't sure which package manager to use, we recommend
+				trying uv, since it supports lockfiles, is extremely fast, and
+				is actively maintained by a full-time team:
+				https://docs.astral.sh/uv/
 
 				For help with using Python on Heroku, see:
 				https://devcenter.heroku.com/articles/getting-started-with-python
@@ -127,6 +128,11 @@ function package_manager::determine_package_manager() {
 
 				Decide which package manager you want to use with your app, and
 				then delete the file(s) and any config from the others.
+
+				If you aren't sure which package manager to use, we recommend
+				trying uv, since it supports lockfiles, is extremely fast, and
+				is actively maintained by a full-time team:
+				https://docs.astral.sh/uv/
 			EOF
 
 			if [[ "${package_managers_found[*]}" == *"poetry"* ]]; then
@@ -138,6 +144,15 @@ function package_manager::determine_package_manager() {
 				EOF
 			fi
 
+			if [[ "${package_managers_found[*]}" == *"uv"* ]]; then
+				output::notice <<-EOF
+					Note: We recently added support for the package manager uv.
+					If you are using a third-party uv buildpack you must remove
+					it, otherwise the requirements.txt file it generates will cause
+					the warning above.
+				EOF
+			fi
+
 			meta_set "package_manager_multiple_found" "$(
 				IFS=,
 				echo "${package_managers_found[*]}"

lib/python_version.sh

@@ -432,6 +432,31 @@ function python_version::warn_if_python_version_file_missing() {
 
 	case "${python_version_origin}" in
 		default | cached)
+			if [[ "${package_manager}" == "uv" ]]; then
+				output::error <<-EOF
+					Error: No Python version was specified.
+
+					When using the package manager uv on Heroku, you must specify
+					your app's Python version with a .python-version file.
+
+					To add a .python-version file:
+
+					1. Make sure you are in the root directory of your app
+					   and not a subdirectory.
+					2. Run 'uv python pin ${python_major_version}'
+					   (adjust to match your app's major Python version).
+					3. Commit the changes to your Git repository using
+					   'git add --all' and then 'git commit'.
+
+					Note: We strongly recommend that you don't specify the Python
+					patch version number in your .python-version file, since it will
+					pin your app to an exact Python version and so stop your app from
+					receiving security updates each time it builds.
+				EOF
+				meta_set "failure_reason" "python-version-file::not-found"
+				exit 1
+			fi
+
 			output::warning <<-EOF
 				Warning: No Python version was specified.
 
@@ -459,6 +484,33 @@ function python_version::warn_if_python_version_file_missing() {
 			EOF
 			;;
 		runtime.txt)
+			if [[ "${package_manager}" == "uv" ]]; then
+				output::error <<-EOF
+					Error: The runtime.txt file isn't supported when using uv.
+
+					When using the package manager uv on Heroku, you must specify
+					your app's Python version with a .python-version file and not
+					a runtime.txt file.
+
+					To switch to a .python-version file:
+
+					1. Make sure you are in the root directory of your app
+					   and not a subdirectory.
+					2. Delete your runtime.txt file.
+					3. Run 'uv python pin ${python_major_version}'
+					   (adjust to match your app's major Python version).
+					4. Commit the changes to your Git repository using
+					   'git add --all' and then 'git commit'.
+
+					Note: We strongly recommend that you don't specify the Python
+					patch version number in your .python-version file, since it will
+					pin your app to an exact Python version and so stop your app from
+					receiving security updates each time it builds.
+				EOF
+				meta_set "failure_reason" "runtime-txt::not-supported"
+				exit 1
+			fi
+
 			output::warning <<-EOF
 				Warning: The runtime.txt file is deprecated.