Add support for Python 3.14 (#1927)

Add support for Python 3.14, and release 3.14.0.

The default Python version remains unchanged (at 3.13) for now.

Release announcement:
https://blog.python.org/2025/10/python-3140-final-is-here.html
https://www.python.org/downloads/release/python-3140/

Details on what's new in Python 3.14:
https://docs.python.org/3.14/whatsnew/3.14.html

The stdlib now has native zstd support, so I've updated the binary
testing script to test that (optional) module was compiled. I've also
expanded the command name tests to test the version specific binary
exists too (eg `python3.14` and not just `python3` / `python`).

Binary builds:
https://github.com/heroku/heroku-buildpack-python/actions/runs/18317304753

Python 3.14 readiness status of the top 360 packages on PyPI:
https://pyreadiness.org/3.14/

Note: We don't yet support the new free-threaded build variants
(e.g.`3.14t`) since they will require further changes to version
handling etc.

Closes #1926.
GUS-W-17595543.
GUS-W-17595545.

Author: edmorley

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Added support for Python 3.14. ([#1927](https://github.com/heroku/heroku-buildpack-python/pull/1927))
 - Stopped using `--with-system-expat` when compiling new Python versions. ([#1925](https://github.com/heroku/heroku-buildpack-python/pull/1925))
 
 ## [v312] - 2025-10-05

README.md

@@ -47,6 +47,7 @@ The current default Python version is: 3.13
 
 The supported Python versions are:
 
+- Python 3.14
 - Python 3.13
 - Python 3.12
 - Python 3.11

builds/build_python_runtime.sh

@@ -32,6 +32,7 @@ case "${STACK:?}" in
 			"3.11"
 			"3.12"
 			"3.13"
+			"3.14"
 		)
 		;;
 	*)
@@ -45,6 +46,10 @@ fi
 
 # Sigstore identities taken from: https://www.python.org/downloads/metadata/sigstore/
 case "${PYTHON_MAJOR_VERSION}" in
+	3.14)
+		SIGSTORE_IDENTITY='hugo@python.org'
+		SIGSTORE_ISSUER='https://github.com/login/oauth'
+		;;
 	3.12 | 3.13)
 		SIGSTORE_IDENTITY='thomas@python.org'
 		SIGSTORE_ISSUER='https://accounts.google.com'

builds/test_python_runtime.sh

@@ -21,10 +21,12 @@ export LD_LIBRARY_PATH="${INSTALL_DIR}/lib/"
 
 tar --zstd --extract --verbose --file "${ARCHIVE_FILEPATH}" --directory "${INSTALL_DIR}"
 
-# Check Python is able to start and is usable via both the default `python3` command and the
-# `python` symlink we create during the build. We use the full filepath rather than adding the
+# Check Python is able to start and is usable via both the default `python3` + `python3.XX` commands
+# and the `python` symlink we create during the build. We use the full filepath rather than adding the
 # directory to PATH to ensure the test doesn't pass because of falling through to system Python.
 "${INSTALL_DIR}/bin/python3" --version
+major_python_version="$("${INSTALL_DIR}/bin/python3" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")"
+"${INSTALL_DIR}/bin/python${major_python_version}" --version
 "${INSTALL_DIR}/bin/python" --version
 
 # Check the Python config script still exists/works after the deletion of scripts with broken shebang lines.
@@ -65,6 +67,14 @@ optional_stdlib_modules=(
 	xml.parsers.expat
 	zlib
 )
+
+# https://docs.python.org/3.14/whatsnew/3.14.html#whatsnew314-zstandard
+if [[ "${major_python_version}" == "3.14" ]]; then
+	optional_stdlib_modules+=(
+		compression.zstd
+	)
+fi
+
 if "${INSTALL_DIR}/bin/python3" -c "import $(
 	IFS=,
 	echo "${optional_stdlib_modules[*]}"

lib/python_version.sh

@@ -9,9 +9,10 @@ LATEST_PYTHON_3_10="3.10.18"
 LATEST_PYTHON_3_11="3.11.13"
 LATEST_PYTHON_3_12="3.12.11"
 LATEST_PYTHON_3_13="3.13.7"
+LATEST_PYTHON_3_14="3.14.0"
 
 OLDEST_SUPPORTED_PYTHON_3_MINOR_VERSION=9
-NEWEST_SUPPORTED_PYTHON_3_MINOR_VERSION=13
+NEWEST_SUPPORTED_PYTHON_3_MINOR_VERSION=14
 
 DEFAULT_PYTHON_FULL_VERSION="${LATEST_PYTHON_3_13}"
 DEFAULT_PYTHON_MAJOR_VERSION="${DEFAULT_PYTHON_FULL_VERSION%.*}"
@@ -420,6 +421,7 @@ function python_version::resolve_python_version() {
 		3.11) echo "${LATEST_PYTHON_3_11}" ;;
 		3.12) echo "${LATEST_PYTHON_3_12}" ;;
 		3.13) echo "${LATEST_PYTHON_3_13}" ;;
+		3.14) echo "${LATEST_PYTHON_3_14}" ;;
 		*) utils::abort_internal_error "Unhandled Python major version: ${requested_python_version}" ;;
 	esac
 }

spec/fixtures/python_3.14/.python-version

@@ -0,0 +1,2 @@
+# Comments are supported
+3.14

spec/fixtures/python_3.14/requirements.txt

@@ -0,0 +1,2 @@
+# This package has been picked since it has no dependencies and is small/fast to install.
+typing-extensions==4.12.2

spec/hatchet/python_version_spec.rb

@@ -5,12 +5,12 @@
 RSpec.shared_examples 'builds with the requested Python version' do |requested_version, resolved_version|
   it "builds with Python #{requested_version}" do
     app.deploy do |app|
-      if requested_version == '3.13'
+      if ['3.9', '3.10', '3.11', '3.12'].include?(requested_version)
         expect(clean_output(app.output)).to include(<<~OUTPUT)
           remote: -----> Python app detected
           remote: -----> Using Python #{requested_version} specified in .python-version
           remote: -----> Installing Python #{resolved_version}
-          remote: -----> Installing pip #{PIP_VERSION}
+          remote: -----> Installing pip #{PIP_VERSION}, setuptools #{SETUPTOOLS_VERSION} and wheel #{WHEEL_VERSION}
           remote: -----> Installing dependencies using 'pip install -r requirements.txt'
           remote:        Collecting typing-extensions==4.12.2 (from -r requirements.txt (line 2))
         OUTPUT
@@ -19,7 +19,7 @@
           remote: -----> Python app detected
           remote: -----> Using Python #{requested_version} specified in .python-version
           remote: -----> Installing Python #{resolved_version}
-          remote: -----> Installing pip #{PIP_VERSION}, setuptools #{SETUPTOOLS_VERSION} and wheel #{WHEEL_VERSION}
+          remote: -----> Installing pip #{PIP_VERSION}
           remote: -----> Installing dependencies using 'pip install -r requirements.txt'
           remote:        Collecting typing-extensions==4.12.2 (from -r requirements.txt (line 2))
         OUTPUT
@@ -242,7 +242,7 @@
             remote:  !     Alternatively, request an older Python version by creating
             remote:  !     a .python-version file in the root directory of your app,
             remote:  !     that contains a Python version like:
-            remote:  !     3.13
+            remote:  !     3.14
             remote: 
             remote:  !     Push rejected, failed to compile Python app.
           OUTPUT
@@ -310,6 +310,12 @@
     it_behaves_like 'builds with the requested Python version', '3.13', LATEST_PYTHON_3_13
   end
 
+  context 'when .python-version contains Python 3.14' do
+    let(:app) { Hatchet::Runner.new('spec/fixtures/python_3.14') }
+
+    it_behaves_like 'builds with the requested Python version', '3.14', LATEST_PYTHON_3_14
+  end
+
   context 'when .python-version contains an invalid Python version string' do
     let(:app) { Hatchet::Runner.new('spec/fixtures/python_version_file_invalid_version', allow_failure: true) }
 
@@ -460,7 +466,7 @@
           remote:  !     https://devcenter.heroku.com/articles/managing-buildpacks#view-your-buildpacks
           remote:  !     https://devcenter.heroku.com/articles/managing-buildpacks#classic-buildpacks-references
           remote:  !     
-          remote:  !     Otherwise, switch to a supported version (such as Python 3.13)
+          remote:  !     Otherwise, switch to a supported version (such as Python 3.14)
           remote:  !     by changing the version in your .python-version file.
           remote: 
           remote:  !     Push rejected, failed to compile Python app.

spec/spec_helper.rb

@@ -15,6 +15,7 @@
 LATEST_PYTHON_3_11 = '3.11.13'
 LATEST_PYTHON_3_12 = '3.12.11'
 LATEST_PYTHON_3_13 = '3.13.7'
+LATEST_PYTHON_3_14 = '3.14.0'
 DEFAULT_PYTHON_FULL_VERSION = LATEST_PYTHON_3_13
 DEFAULT_PYTHON_MAJOR_VERSION = DEFAULT_PYTHON_FULL_VERSION.gsub(/\.\d+$/, '')