Error when multiple package manager files are found (#1993)

Currently the buildpack will use whichever package manager it finds
first, if the files of multiple package managers are found.

This occasionally results in support tickets where the user believes the
build to not be installing dependencies correctly, when in fact they are
adding dependencies to the wrong package manager file.

It also means historic users of third-party Poetry and uv buildpacks
might not realise that the buildpack now natively supports those package
managers (in a much more efficient way), if they missed our release
announcements.

As such, in November 2024 in #1692 a warning was added, which we're now
converting to an error.

Users with multiple package manager files committed to their Git repo
will need to pick one package manager and delete the files relating to
the others.

And users who are still using the third-party Poetry or uv buildpacks
will need to remove those buildpacks from their app:
https://devcenter.heroku.com/articles/managing-buildpacks#remove-classic-buildpacks

Closes #1691.
GUS-W-18915632.

Author: edmorley

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- The build now errors if the files for multiple package managers are found. This replaces the warning displayed since November 2024. ([#1993](https://github.com/heroku/heroku-buildpack-python/pull/1993))
 - Sunset the previously deprecated support for falling back to installing dependencies from a `setup.py` file if no Python package manager files were found. ([#1992](https://github.com/heroku/heroku-buildpack-python/pull/1992))
 
 ## [v324] - 2025-12-09

lib/package_manager.sh

@@ -44,11 +44,6 @@ function package_manager::determine_package_manager() {
 		package_managers_found_display_text+=("requirements.txt (pip)")
 	fi
 
-	# This must be after the requirements.txt check, so that the requirements.txt exported by
-	# `python-poetry-buildpack` takes precedence over poetry.lock, for consistency with the
-	# behaviour prior to this buildpack supporting Poetry natively. In the future the presence
-	# of multiple package manager files will be turned into an error, at which point the
-	# ordering here won't matter.
 	if [[ -f "${build_dir}/poetry.lock" ]]; then
 		package_managers_found+=(poetry)
 		package_managers_found_display_text+=("poetry.lock (Poetry)")
@@ -132,57 +127,38 @@ function package_manager::determine_package_manager() {
 			exit 1
 			;;
 		*)
-			# If multiple package managers are found, use the first found above.
-			# TODO: Turn this case into an error since it results in support tickets from users
-			# who don't realise they have multiple package manager files and think their changes
-			# aren't taking effect. (We'll need to wait until after Poetry support has landed,
-			# and people have had a chance to migrate from the Poetry buildpack mentioned above.)
-			echo "${package_managers_found[0]}"
-
-			output::warning <<-EOF
-				Warning: Multiple Python package manager files were found.
+			output::error <<-EOF
+				Error: Multiple Python package manager files were found.
 
 				Exactly one package manager file should be present in your app's
 				source code, however, several were found:
 
 				$(printf -- "%s\n" "${package_managers_found_display_text[@]}")
 
-				For now, we will build your app using the first package manager
-				listed above, however, in the future this warning will become
-				an error.
+				Previously, the buildpack guessed which package manager to use
+				and installed your dependencies with the first package manager
+				listed above. However, this implicit behaviour was deprecated
+				in November 2024 and is now no longer supported.
 
-				Decide which package manager you want to use with your app, and
-				then delete the file(s) and any config from the others.
+				You must 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
-				output::notice <<-EOF
-					Note: We recently added support for the package manager Poetry.
-					If you are using a third-party Poetry buildpack you must remove
-					it, otherwise the requirements.txt file it generates will cause
-					the warning above.
-				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
-
-			build_data::set_string "package_manager_multiple_found" "$(
+				Note: If you use a third-party uv or Poetry buildpack, you must
+				remove it from your app, since it's no longer required and the
+				requirements.txt file it generates will trigger this error. See:
+				https://devcenter.heroku.com/articles/managing-buildpacks#remove-classic-buildpacks
+			EOF
+			build_data::set_string "failure_reason" "package-manager::multiple-found"
+			build_data::set_string "failure_detail" "$(
 				IFS=,
 				echo "${package_managers_found[*]}"
 			)"
-			return 0
+			exit 1
 			;;
 	esac
 }

spec/fixtures/multiple_package_managers/.python-version

@@ -1,6 +0,0 @@
-[[source]]
-url = "https://pypi.org/simple"
-verify_ssl = true
-name = "pypi"
-
-[packages]

spec/fixtures/multiple_package_managers/Pipfile

@@ -87,56 +87,44 @@
     end
   end
 
-  # This case will be turned into an error in the future.
   context 'when there are multiple package manager files' do
-    let(:app) { Hatchet::Runner.new('spec/fixtures/multiple_package_managers') }
+    let(:app) { Hatchet::Runner.new('spec/fixtures/multiple_package_managers', allow_failure: true) }
 
-    it 'outputs a warning and builds with the first listed' do
+    it 'fails the build with an informative error message' do
       app.deploy do |app|
-        expect(clean_output(app.output)).to match(Regexp.new(<<~REGEX))
+        expect(clean_output(app.output)).to include(<<~OUTPUT)
           remote: -----> Python app detected
           remote: 
-          remote:  !     Warning: Multiple Python package manager files were found.
+          remote:  !     Error: Multiple Python package manager files were found.
           remote:  !     
           remote:  !     Exactly one package manager file should be present in your app's
           remote:  !     source code, however, several were found:
           remote:  !     
-          remote:  !     Pipfile.lock \\(Pipenv\\)
-          remote:  !     requirements.txt \\(pip\\)
-          remote:  !     poetry.lock \\(Poetry\\)
-          remote:  !     uv.lock \\(uv\\)
+          remote:  !     Pipfile.lock (Pipenv)
+          remote:  !     requirements.txt (pip)
+          remote:  !     poetry.lock (Poetry)
+          remote:  !     uv.lock (uv)
           remote:  !     
-          remote:  !     For now, we will build your app using the first package manager
-          remote:  !     listed above, however, in the future this warning will become
-          remote:  !     an error.
+          remote:  !     Previously, the buildpack guessed which package manager to use
+          remote:  !     and installed your dependencies with the first package manager
+          remote:  !     listed above. However, this implicit behaviour was deprecated
+          remote:  !     in November 2024 and is now no longer supported.
           remote:  !     
-          remote:  !     Decide which package manager you want to use with your app, and
-          remote:  !     then delete the file\\(s\\) and any config from the others.
+          remote:  !     You must decide which package manager you want to use with your
+          remote:  !     app, and then delete the file(s) and any config from the others.
           remote:  !     
           remote:  !     If you aren't sure which package manager to use, we recommend
           remote:  !     trying uv, since it supports lockfiles, is extremely fast, and
           remote:  !     is actively maintained by a full-time team:
           remote:  !     https://docs.astral.sh/uv/
+          remote:  !     
+          remote:  !     Note: If you use a third-party uv or Poetry buildpack, you must
+          remote:  !     remove it from your app, since it's no longer required and the
+          remote:  !     requirements.txt file it generates will trigger this error. See:
+          remote:  !     https://devcenter.heroku.com/articles/managing-buildpacks#remove-classic-buildpacks
           remote: 
-          remote: 
-          remote:  !     Note: We recently added support for the package manager Poetry.
-          remote:  !     If you are using a third-party Poetry buildpack you must remove
-          remote:  !     it, otherwise the requirements.txt file it generates will cause
-          remote:  !     the warning above.
-          remote: 
-          remote: 
-          remote:  !     Note: We recently added support for the package manager uv.
-          remote:  !     If you are using a third-party uv buildpack you must remove
-          remote:  !     it, otherwise the requirements.txt file it generates will cause
-          remote:  !     the warning above.
-          remote: 
-          remote: -----> Using Python #{DEFAULT_PYTHON_MAJOR_VERSION} specified in .python-version
-          remote: -----> Installing Python #{DEFAULT_PYTHON_FULL_VERSION}
-          remote: -----> Installing Pipenv #{PIPENV_VERSION}
-          remote: -----> Installing dependencies using 'pipenv install --deploy'
-          remote:        Installing dependencies from Pipfile.lock \\(.+\\)...
-          remote: -----> Saving cache
-        REGEX
+          remote:  !     Push rejected, failed to compile Python app.
+        OUTPUT
       end
     end
   end