Fix Netlify configuration to allow CI to pass: likely Python version too new

[PLeVasseur]

Looks to be an issue with the Python version being too new and the ecosystem not having caught up yet. Possibly?

Pulled from here.

5:15:56 PM: Build command from Netlify app                                
5:15:56 PM: ────────────────────────────────────────────────────────────────
5:15:56 PM: ​
5:15:56 PM: $ curl -LsSf https://astral.sh/uv/install.sh | sh && ./make.py
5:15:56 PM: downloading uv 0.9.4 x86_64-unknown-linux-gnu
5:15:56 PM: no checksums to verify
5:15:56 PM: installing to /opt/buildhome/.local/bin
5:15:56 PM:   uv
5:15:56 PM:   uvx
5:15:56 PM: everything's installed!
Using CPython 3.14.0 interpreter at: /opt/buildhome/.local/share/mise/installs/python/3.14.0/bin/python3
5:15:56 PM: Creating virtual environment at: .venv
5:15:56 PM:    Building builder @ file:///opt/build/repo/builder
5:15:56 PM:    Building m2r==0.3.1
5:15:56 PM: Downloading pygments (1.2MiB)
5:15:56 PM: Downloading sphinx-needs (2.5MiB)
5:15:56 PM: Downloading sphinx (3.4MiB)
5:15:56 PM: Downloading babel (9.7MiB)
5:15:56 PM: Downloading sphinx-rtd-theme (7.3MiB)
5:15:56 PM: Downloading ruff (11.1MiB)
5:15:57 PM:    Building rpds-py==0.23.1
5:15:57 PM:    Building markupsafe==3.0.2
5:15:57 PM:    Building watchfiles==1.0.5
5:15:57 PM:  Downloading pygments
5:15:57 PM:  Downloading ruff
5:15:57 PM:  Downloading sphinx-rtd-theme
5:15:57 PM:  Downloading sphinx-needs
5:15:57 PM:  Downloading sphinx
5:15:57 PM:  Downloading babel
5:15:57 PM:   × Failed to build `watchfiles==1.0.5`
5:15:57 PM:   ├─▶ The build backend returned an error
5:15:57 PM:   ╰─▶ Call to `maturin.build_wheel` failed (exit status: 1)
5:15:57 PM:       [stdout]
5:15:57 PM:       Running `maturin pep517 build-wheel -i
      /opt/buildhome/.cache/uv/builds-v0/.tmpZv6bLS/bin/python --compatibility
      off`
5:15:57 PM:       [stderr]
5:15:57 PM:       error: rustup could not choose a version of cargo to run, because one
5:15:57 PM:       wasn't specified explicitly, and no default is configured.
      help: run 'rustup default stable' to download the latest stable release
5:15:57 PM:       of Rust and set it as your default toolchain.
5:15:57 PM:       💥 maturin failed
5:15:57 PM:         Caused by: Cargo metadata failed. Does your crate compile with `cargo
      build`?
5:15:57 PM:         Caused by: `cargo metadata` exited with an error:
5:15:57 PM:       Error: command ['maturin', 'pep517', 'build-wheel', '-i',
5:15:57 PM:       '/opt/buildhome/.cache/uv/builds-v0/.tmpZv6bLS/bin/python',
5:15:57 PM:       '--compatibility', 'off'] returned non-zero exit status 1
5:15:57 PM:       hint: This usually indicates a problem with the package or the build
5:15:57 PM:       environment.
5:15:57 PM:   help: `watchfiles` (v1.0.5) was included because
5:15:57 PM:         `safety-critical-rust-coding-guidelines` (v0.1.0) depends on
5:15:57 PM:         `sphinx-autobuild` (v2024.10.3) which depends on `watchfiles`
5:15:57 PM: ​
5:15:57 PM: "build.command" failed                                        
5:15:57 PM: ────────────────────────────────────────────────────────────────
5:15:57 PM: ​
5:15:57 PM:   Error message
5:15:57 PM:   Command failed with exit code 1: curl -LsSf https://astral.sh/uv/install.sh | sh && ./make.py (https://ntl.fyi/exit-code-1)
5:15:57 PM: ​
5:15:57 PM:   Error location
5:15:57 PM:   In Build command from Netlify app:
5:15:57 PM:   curl -LsSf https://astral.sh/uv/install.sh | sh && ./make.py
5:15:57 PM: ​
5:15:57 PM:   Resolved config
5:15:57 PM:   build:
5:15:57 PM:     command: curl -LsSf https://astral.sh/uv/install.sh | sh && ./make.py
5:15:57 PM:     commandOrigin: ui
5:15:57 PM:     environment:
5:15:57 PM:       - REVIEW_ID
5:15:57 PM:     publish: /opt/build/repo/build/html
5:15:57 PM:     publishOrigin: ui
5:15:57 PM: Build failed due to a user error: Build script returned non-zero exit code: 2
5:15:58 PM: Failed during stage 'building site': Build script returned non-zero exit code: 2 (https://ntl.fyi/exit-code-2)
5:15:58 PM: Failing build: Failed to build site
5:15:58 PM: Finished processing build request in 12.349s

Over on a different step, build, it looks to succeed:

Trying to find version for uv in: /home/runner/work/safety-critical-rust-coding-guidelines/safety-critical-rust-coding-guidelines/uv.toml
Could not find file: /home/runner/work/safety-critical-rust-coding-guidelines/safety-critical-rust-coding-guidelines/uv.toml
Trying to find version for uv in: /home/runner/work/safety-critical-rust-coding-guidelines/safety-critical-rust-coding-guidelines/pyproject.toml
Could not determine uv version from uv.toml or pyproject.toml. Falling back to latest.
Getting latest version from GitHub API...
manifest-file not provided, reading from local file.
manifest-file does not contain version 0.9.5, arch x86_64, platform unknown-linux-gnu. Falling back to GitHub releases.
Downloading uv from "https://github.com/astral-sh/uv/releases/download/0.9.5/uv-x86_64-unknown-linux-gnu.tar.gz" ...
/usr/bin/tar xz --warning=no-unknown-keyword --overwrite -C /home/runner/work/_temp/467d8595-6204-43a2-9331-eef10ec5b1fe -f /home/runner/work/_temp/df45fa58-2f55-441e-9b08-1ab9cfffc257
Added /home/runner/.local/bin to the path
Added /opt/hostedtoolcache/uv/0.9.5/x86_64 to the path
Set UV_CACHE_DIR to /home/runner/work/_temp/setup-uv-cache
Successfully installed uv version 0.9.5

... other stuff ...

Using CPython 3.12.3 interpreter at: /usr/bin/python3
Creating virtual environment at: .venv
   Building builder @ file:///home/runner/work/safety-critical-rust-coding-guidelines/safety-critical-rust-coding-guidelines/builder
Downloading pygments (1.2MiB)
Downloading sphinx-rtd-theme (7.3MiB)
Downloading babel (9.7MiB)
Downloading sphinx-needs (2.5MiB)
Downloading ruff (11.1MiB)
Downloading sphinx (3.4MiB)
 Downloading pygments
 Downloading sphinx-needs
 Downloading sphinx
      Built builder @ file:///home/runner/work/safety-critical-rust-coding-guidelines/safety-critical-rust-coding-guidelines/builder
 Downloading sphinx-rtd-theme
 Downloading babel
 Downloading ruff
Installed 48 packages in 66ms

I see some obvious differences -- the versions of uv being used and the CPython versions being used.

Here is a Netlify step that passed about 2 weeks ago:

4:28:24 PM: $ curl -LsSf https://astral.sh/uv/install.sh | sh && ./make.py
4:28:24 PM: downloading uv 0.8.23 x86_64-unknown-linux-gnu
4:28:24 PM: no checksums to verify
4:28:25 PM: installing to /opt/buildhome/.local/bin
4:28:25 PM:   uv
4:28:25 PM:   uvx
4:28:25 PM: everything's installed!
Using CPython 3.13.7 interpreter at: /opt/buildhome/.local/share/mise/installs/python/3.13.7/bin/python3
4:28:25 PM: Creating virtual environment at: .venv
4:28:25 PM:    Building builder @ file:///opt/build/repo/builder
4:28:25 PM: Downloading sphinx-rtd-theme (7.3MiB)
4:28:25 PM: Downloading pygments (1.2MiB)
4:28:25 PM: Downloading babel (9.7MiB)
4:28:25 PM: Downloading ruff (11.1MiB)
4:28:25 PM: Downloading sphinx-needs (2.5MiB)
4:28:25 PM: Downloading sphinx (3.4MiB)
4:28:25 PM:    Building m2r==0.3.1
4:28:25 PM:  Downloading pygments
4:28:26 PM:  Downloading sphinx-rtd-theme
4:28:26 PM:  Downloading sphinx
4:28:26 PM:  Downloading ruff
4:28:26 PM:  Downloading sphinx-needs
4:28:26 PM:  Downloading babel
4:28:26 PM:       Built m2r==0.3.1
4:28:26 PM:       Built builder @ file:///opt/build/repo/builder

Note that the uv version and CPython version also differ.

[PLeVasseur]

Here's what ChatGPT had to say:

Yep — this is a classic “brand-new Python + no wheel → tries to compile Rust → no Rust toolchain” failure.

What’s going on:

• Your Netlify build is picking CPython 3.14.0. Many projects don’t have Linux wheels for 3.14 yet. When watchfiles==1.0.5 can’t find a wheel, it falls back to building from source with maturin, which needs a Rust toolchain. Netlify’s image doesn’t have rustup/cargo, so the build aborts. ([Python.org]1)
• The dependency chain comes via sphinx-autobuild (2024.10.3), which uses watchfiles. If you don’t actually need the live-reload server at build time, you’re paying for a dev tool in CI. ([FreshPorts]2)

Why it worked before:

• Earlier logs show Python 3.13.7 (or 3.12 on GH Actions). Those versions have widely available wheels, so no Rust build step was needed, and everything sailed through. (watchfiles provides prebuilt wheels when available; only falls back to Rust otherwise.) ([GitHub]3)

Fixes (pick one)

1. Pin Python on Netlify to 3.12 or 3.13 (recommended)
   3.12/3.13 have wheels for your stack, avoiding Rust entirely.

• In Netlify UI → Site settings → Environment variables, set:

  • PYTHON_VERSION = 3.12 (or 3.13)
    (Alternatively add a runtime.txt with 3.12 at repo root.) ([Stack Overflow]4)

• If uv is choosing a system Python anyway, force it:

  • Set UV_PYTHON=3.12 (and optionally UV_PYTHON_PREFERENCE=only-managed) or invoke uv with --python 3.12 from your make.py. ([Astral Docs]5)

2. Don’t install dev tools during Netlify builds
   If sphinx-autobuild is only for local docs preview, exclude it from the Netlify install. With uv, use dependency groups (e.g., install only the default/prod group) so watchfiles never enters the solve.

3. Pin sphinx-autobuild (or watchfiles) to a combo with wheels available
   Short-term workaround: pin to a version that has manylinux wheels for your target Python, or avoid the watchfiles requirement by staying on an older sphinx-autobuild used pre-watchfiles (if that fits your needs). ([FreshPorts]2)

4. Install Rust before building
   If you must stay on 3.14, add Rust to the Netlify build command so maturin can compile:

curl https://sh.rustup.rs -sSf | sh -s -- -y
source "$HOME/.cargo/env"
rustup default stable
curl -LsSf https://astral.sh/uv/install.sh | sh && ./make.py

(This fixes the immediate error, but builds will be slower and you may hit other 3.14 wheel gaps.)

---

Is anyone else broken?

Yes — Python 3.14.0 was released Oct 7, 2025, and there’s a typical lag before popular projects publish wheels for new CPython versions. CI systems that silently “upgrade to latest” Python are seeing similar fallout right now. ([Python.org]1)

---

What I’d do for your repo

• Add PYTHON_VERSION=3.12 (or 3.13) on Netlify.
• Ensure your make.py/uv install only the dependencies needed to build docs (exclude sphinx-autobuild).
• Optionally add .python-version to align local/CI Python and avoid surprises.

If you want, paste your pyproject.toml relevant bits and your make.py install command — I’ll tweak the exact uv flags to keep Netlify on 3.12 and skip dev extras cleanly.