sagemath · vbraun · Apr 8, 2026 · Oct 31, 2025 · Oct 31, 2025 · Nov 1, 2025
diff --git a/.github/workflows/ci-distro.yml b/.github/workflows/ci-distro.yml
@@ -53,7 +53,7 @@ jobs:
       targets: build
       targets_optional: ptestlong
       tox_system_factors: >-
-          ["ubuntu-jammy"]
+          ["ubuntu-noble"]
       tox_packages_factors: >-
           ["minimal"]
       docker_push_repository: ghcr.io/${{ github.repository }}/
@@ -89,6 +89,10 @@ jobs:
         with:
           python-version: "3.13"
 
+      - name: Install Python packages
+        run: |
+          pip install setuptools
+
       - name: Install dependencies
         run: |
           eval $(build/bin/sage-print-system-package-command homebrew update)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
@@ -16,15 +16,15 @@ on:
         description: 'Stringified JSON object listing tox system factors'
         type: string
         # 'tox -e update_docker_platforms' updates below
+        # Only distros with Python 3.12+ are supported (Sage now requires system Python 3.12+)
         default: >-
           [
-           "ubuntu-jammy",
            "ubuntu-noble",
-           "debian-bullseye",
-           "debian-bookworm",
-           "fedora-40",
-           "fedora-41",
-           "centos-stream-9",
+           "ubuntu-resolute",
+           "debian-trixie",
+           "fedora-42",
+           "fedora-43",
+           "centos-stream-10",
            "opensuse-tumbleweed",
           ]
         # 'tox -e update_docker_platforms' updates above
@@ -280,4 +280,4 @@ jobs:
           else
              echo "No Docker images created."
           fi
-        if: always() && ${{ inputs.docker_push_repository }}
+        if: ${{ always() && inputs.docker_push_repository }}
diff --git a/README.md b/README.md
@@ -31,7 +31,6 @@ Table of Contents
 * [Build System](#build-system)
 * [Relocation](#relocation)
 * [Redistribution](#redistribution)
-* [Build System](#build-system)
 * [Changes to Included Software](#changes-to-included-software)
 
 Getting Started
@@ -210,8 +209,9 @@ in the Installation Guide.
 
 4.  [Linux, WSL] Install the required minimal build prerequisites:
 
-    - Compilers: `gcc`, `gfortran`, `g++` (GCC versions from 8.4.0 to 13.x
-      and recent versions of Clang (LLVM) are supported).
+    - Compilers: `gcc`, `gfortran`, `g++`, or other suitable C, C++, and
+      Fortran compilers. Sage's classical build checks for a C compiler that
+      can compile C99 code and a C++ compiler with C++11 support.
       See [build/pkgs/gcc/SPKG.rst](build/pkgs/gcc/SPKG.rst) and
       [build/pkgs/gfortran/SPKG.rst](build/pkgs/gfortran/SPKG.rst)
       for a discussion of suitable compilers.
@@ -221,11 +221,14 @@ in the Installation Guide.
       See [build/pkgs/_prereq/SPKG.rst](build/pkgs/_prereq/SPKG.rst) for
       more details.
 
-    - Python 3.4 or later, or Python 2.7, a full installation including
-      `urllib`; but ideally version 3.12.x or later, which
-      will avoid having to build Sage's own copy of Python 3.
-      See [build/pkgs/python3/SPKG.rst](build/pkgs/python3/SPKG.rst)
-      for more details.
+    - Python 3.12 or newer with a full standard library installation.
+      Sage no longer builds its own copy of Python; you must provide a
+      system Python or another external Python installation.
+      Sage's `./configure` currently requires Python `>= 3.12` and `< 3.15`,
+      with modules including `sqlite3`, `ctypes`, `math`, `hashlib`,
+      `socket`, `ssl`, `ensurepip`, and `zlib`.
+      See the [installation guide](https://doc.sagemath.org/html/en/installation/source-distro.html#using-an-external-python-installed-by-uv)
+      for details on using a system or `uv`-managed Python.
 
     We have collected lists of system packages that provide these build
     prerequisites. See, in the folder
@@ -363,6 +366,20 @@ in the Installation Guide.
     For example, to build Sage with `gf2x` package supplied by Sage,
     use `./configure --with-system-gf2x=no`.
 
+    Sage no longer builds its own copy of Python, so `./configure` must
+    find a suitable external interpreter. If you want to use a Python
+    installed with `uv` instead of your system package manager's Python,
+    Sage's `./configure` check currently expects Python `>= 3.12` and
+    `< 3.15`. On Python 3.12 and newer, it also requires `setuptools`,
+    because the configure test creates a fresh virtual environment from
+    the selected interpreter and builds small extension modules there.
+    For a `uv`-managed Python, one working setup is:
+
+        $ uv python install 3.13
+        $ PYTHON3="$(uv python find --managed-python --resolve-links 3.13)"
+        $ uv pip install --python "$PYTHON3" --break-system-packages setuptools
+        $ ./configure --with-python="$PYTHON3"
+
     At the end of a successful `./configure` run, you may see messages
     recommending to install extra system packages using your package
     manager.
@@ -486,6 +503,7 @@ SAGE_ROOT                 Root directory (create by git clone)
 ├── configure             Top-level configure script
 ├── COPYING.txt           Copyright information
 ├── local  (SAGE_LOCAL)   Installation hierarchy for non-Python packages
+│                         and shared runtime files
 │   ├── bin               Executables
 │   ├── include           C/C++ headers
 │   ├── lib               Shared libraries, architecture-dependent data
@@ -541,9 +559,13 @@ and its associated user interfaces, and the larger software distribution of
 Sage's main dependencies (for those dependencies not supplied by the user's
 system).
 
-Sage's Python library is built and installed using a `setup.py` script as is
-standard for Python packages (Sage's `setup.py` is non-trivial, but not
-unusual).
+Sage no longer builds its own Python interpreter. Instead, `./configure`
+selects a system or other external Python (`>= 3.12`, `< 3.15`) and uses it
+to create `SAGE_VENV`.
+
+Sage's Python library is built and installed as a standard Python project via
+`pip install .`, using the metadata in `pyproject.toml` and the
+`meson-python` build backend.
 
 Most of the rest of the build system is concerned with building all of Sage's
 dependencies in the correct order in relation to each other.  The dependencies
@@ -567,18 +589,18 @@ The `configure` script itself, if it is not already built, can be generated by
 running the `bootstrap` script (the latter requires _GNU autotools_ being installed).
 The top-level `Makefile` also takes care of this automatically.
 
-To summarize, running a command like `make python3` at the top-level of the
+To summarize, running a command like `make sagelib` at the top-level of the
 source tree goes something like this:
 
-1.  `make python3`
+1.  `make sagelib`
 2.  run `./bootstrap` if `configure` needs updating
 3.  run `./configure` with any previously configured options if `build/make/Makefile`
     needs updating
 4.  change directory into `build/make` and run the `install` script--this is
-    little more than a front-end to running `make -f build/make/Makefile python3`,
+    little more than a front-end to running `make -f build/make/Makefile sagelib`,
     which sets some necessary environment variables and logs some information
-5.  `build/make/Makefile` contains the actual rule for building `python3`; this
-    includes building all of `python3`'s dependencies first (and their
+5.  `build/make/Makefile` contains the actual rule for building `sagelib`; this
+    includes building all of `sagelib`'s dependencies first (and their
     dependencies, recursively); the actual package installation is performed
     with the `sage-spkg` program
 
@@ -629,4 +651,3 @@ part of the Sage git repository.
 <p align="center">
    https://www.sagemath.org
 </p>
-
diff --git a/build/bin/sage-bootstrap-python b/build/bin/sage-bootstrap-python
diff --git a/build/bin/sage-build-num-threads b/build/bin/sage-build-num-threads
@@ -1,4 +1,4 @@
-#!/usr/bin/env sage-bootstrap-python
+#!/usr/bin/env python3
 #
 # Determine the number of threads to be used by Sage.
 #

diff --git a/build/bin/sage-download-file b/build/bin/sage-download-file
@@ -1,4 +1,4 @@
-#!/usr/bin/env sage-bootstrap-python
+#!/usr/bin/env python3
 
 # USAGE:
 #

diff --git a/build/bin/sage-flock b/build/bin/sage-flock
@@ -1,4 +1,4 @@
-#!/usr/bin/env sage-bootstrap-python
+#!/usr/bin/env python3
 # vim: set filetype=python:
 
 # USAGE:

diff --git a/build/bin/sage-print-system-package-command b/build/bin/sage-print-system-package-command
@@ -97,7 +97,7 @@ function print_shell_command()
     if [ -z "$WRAP" -o $# -lt 6 ]; then
         echo "${PROMPT}${quoted}"
     else
-        sage-bootstrap-python -c "import textwrap; print(' \\\\\n'.join(textwrap.wrap(r'''${quoted}''', $WRAP, initial_indent=r'''${PROMPT}''', subsequent_indent=r'''${CONTINUATION}''', break_long_words=False, break_on_hyphens=False)))"
+        python3 -c "import textwrap; print(' \\\\\n'.join(textwrap.wrap(r'''${quoted}''', $WRAP, initial_indent=r'''${PROMPT}''', subsequent_indent=r'''${CONTINUATION}''', break_long_words=False, break_on_hyphens=False)))"
     fi
     if [ -n "$OUTPUT_RST" ]; then
         echo

diff --git a/build/bin/sage-spkg-installcheck b/build/bin/sage-spkg-installcheck
@@ -1,4 +1,4 @@
-#!/usr/bin/env sage-bootstrap-python
+#!/usr/bin/env python3
 
 # usage: sage-spkg-installcheck [-h] PKG [SAGE_LOCAL]
 #

diff --git a/build/bin/sage-spkg-uninstall b/build/bin/sage-spkg-uninstall
@@ -1,4 +1,4 @@
-#!/usr/bin/env sage-bootstrap-python
+#!/usr/bin/env python3
 
 # usage: sage-spkg-uninstall [-h] PKG [SAGE_LOCAL]
 #

diff --git a/build/bin/sage-uncompress-spkg b/build/bin/sage-uncompress-spkg
@@ -1,4 +1,4 @@
-#!/usr/bin/env sage-bootstrap-python
+#!/usr/bin/env python3
 
 # usage: sage-uncompress-spkg [-h] [-d DIR] PKG [FILE]
 #

diff --git a/build/make/Makefile.in b/build/make/Makefile.in
@@ -33,7 +33,6 @@ SPKG_INST_RELDIR = var/lib/sage/installed
 
 # Aliases for mutually exclusive standard packages selected at configure time
 TOOLCHAIN = @SAGE_TOOLCHAIN@
-PYTHON = python3
 MP_LIBRARY = gmp
 BLAS = openblas
 
@@ -221,12 +220,7 @@ ifneq ($(PYTHON_FOR_VENV),)
 # 3 only).  $(PYTHON) is set in Makefile to python3_venv.
 # Thus $(inst_python3_venv) will an (order-only) dependency of every Python package.
 #
-# TODO: If we reconfigure to build our own Python after having used the system
-# Python, files installed to create the virtualenv should be *removed*.  That
-# could either be done here by the makefile, or in an spkg-preinst for python3
-ifeq ($(PYTHON),python3)
 PYTHON = python3_venv
-endif
 inst_python3_venv = $(SAGE_VENV)/$(SPKG_INST_RELDIR)/python3_venv-3.$(PYTHON_MINOR)-$(subst /,-,$(PYTHON_FOR_VENV))$(findstring --system-site-packages,$(SAGE_VENV_FLAGS))
 
 $(SAGE_VENV)/$(SPKG_INST_RELDIR):
@@ -313,9 +307,8 @@ all-toolchain: base-toolchain
 PYTHON_TOOLCHAIN = setuptools pip setuptools_scm wheel flit_core hatchling python_build meson_python
 
 # Issue #32056: Avoid installed setuptools leaking into the build of python3 by uninstalling it.
-# It will have to be reinstalled anyway because of its dependency on $(PYTHON).
-python3-SAGE_LOCAL-no-deps: setuptools-clean
-python3-SAGE_VENV-no-deps: setuptools-clean
+# python3-SAGE_LOCAL-no-deps: setuptools-clean
+# python3-SAGE_VENV-no-deps: setuptools-clean
 
 # Everything needed to start up Sage using "./sage".  Of course, not
 # every part of Sage will work.  It does not include Maxima for example.

diff --git a/build/pkgs/_bootstrap/SPKG.rst b/build/pkgs/_bootstrap/SPKG.rst
@@ -7,3 +7,50 @@ Description
 This optional script package represents the requirements (system packages)
 that are needed in addition to those represented by the ``_prereq`` package
 in order to run the top-level ``bootstrap`` script.
+
+Namely, the following standard tools must be installed on your computer:
+
+- **liblzma/xz**: XZ Utils, the free general-purpose data compression software
+  with a high compression ratio.
+- **python**: Python 3.12 or later from your system package manager or another
+  external installation. Sage no longer builds its own Python interpreter; it
+  uses this interpreter to create ``SAGE_VENV``. It needs to have the
+  development headers and the following standard modules available:
+  sqlite3, ctypes, math, hashlib, socket, ssl, ensurepip, zlib, setuptools
+
+XZ Utils (liblzma) is available with most supported distributions (package
+names such as ``xz-devel`` on Fedora, ``liblzma-dev`` on Debian/Ubuntu).
+It can also be built from source from https://github.com/tukaani-project/xz.
+After downloading and untarring the release archive, and changing to the
+directory with the sources::
+
+    $ ./configure --prefix=/usr/local && make && make install
+
+will install XZ Utils in ``/usr/local``. Instead of ``/usr/local`` one may choose
+another location, say ``/opt/foo``. A modern xz/liblzma installs a
+``liblzma.pc`` file, and Sage's ``./configure`` checks for it using a
+pkg-config macro. To detect xz/liblzma at a non-standard location, add it
+to ``PKG_CONFIG_PATH``::
+
+    $ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/opt/foo/lib/pkgconfig
+
+Python 3.12 (or later) with development headers is available with most
+supported distributions (package names such as ``python3-devel`` on Fedora,
+``python3-dev`` on Debian/Ubuntu).
+It can also be built from source from https://www.python.org/downloads/.
+After downloading and untarring the release archive, and changing to the
+directory with the sources::
+
+    $ ./configure --prefix=/usr/local --enable-optimizations --with-ensurepip=install && make && make install
+
+will install Python in ``/usr/local``; this takes a few minutes on a
+moderately fast machine. Instead of ``/usr/local`` one may choose another
+location, say ``/opt/foo``, which then should be passed to Sage's
+``./configure`` with ``--with-python=/opt/foo/bin/python3``.
+The ``--enable-optimizations`` flag is optional but recommended for
+performance. Make sure that the prerequisites for the required standard
+modules (``sqlite3``, ``ctypes``, ``zlib``, ``ssl``, etc.) are installed
+before building Python; otherwise these modules will be missing.
+
+It is also possible to use a Python installed by `uv <https://docs.astral.sh/uv/>`_
+and pass it to ``./configure`` with ``--with-python=...``.
diff --git a/build/pkgs/_bootstrap/distros/alpine.txt b/build/pkgs/_bootstrap/distros/alpine.txt
@@ -3,3 +3,9 @@ gettext-dev
 autoconf
 automake
 libtool
+# Python packages needed for configure and build
+python3
+python3-dev
+py3-setuptools
+xz
+xz-dev
diff --git a/build/pkgs/_bootstrap/distros/arch.txt b/build/pkgs/_bootstrap/distros/arch.txt
@@ -2,3 +2,7 @@
 autoconf
 automake
 libtool
+# Python packages needed for configure and build
+python
+python-setuptools
+xz
diff --git a/build/pkgs/_bootstrap/distros/conda.txt b/build/pkgs/_bootstrap/distros/conda.txt
@@ -2,3 +2,8 @@
 autoconf
 automake
 libtool
+# Python packages needed for configure and build
+python
+setuptools
+xz
+xz