Skip to content

feat: install CPython from uv-build by default on Linux and macOS - #62

Merged
linghengqian merged 10 commits into
mainfrom
feat/uv-build-default
Nov 14, 2026
Merged

linghengqian merged 10 commits into
mainfrom
feat/uv-build-default

Conversation

@linghengqian

@linghengqian linghengqian commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Summary

On Linux and macOS, a CPython install now takes the prebuilt uv-build archive when the uv-build index lists the version, and builds from source with pyenv otherwise. Windows, GraalPy, PyPy and Conda keep their current paths.

A default install no longer needs a C toolchain or the -dev packages a source build needs. uv-build archives are the python-build-standalone builds that uv itself installs CPython from. Installs that already exist are not touched.

Behaviour

VFOX_PYTHON_USE_UV_BUILD CPython on Linux and macOS
unset (new default) uv-build archive when the index lists the version; pyenv source build otherwise
0, false, no, off pyenv source build for every CPython
1, true, yes, on uv-build only; a version the index lacks is an error
  • vfox search python lists the pyenv names together with the CPython releases only the index lists. Every list is newest first, and pyenv -dev snapshots sort last.
  • A partial name such as python@3.12 resolves in the index first, so it installs the newest 3.12 that has an archive. Only a line the index does not list falls back to the combined list, and is built from source.
  • latest is the first entry of the list that is not a free-threaded build. It is not resolved in the index. A free-threaded build such as 3.13.18t is installed only when its name asks for it, even when it is newer than every standard release.
  • An index request is sent again on a network error, HTTP 429, a 5xx, or a 200 response that is not the index, such as a captive portal page. There are three attempts in all. Before a retry the plugin waits for the server's Retry-After in seconds when it is at most ten; otherwise it waits one second, then two. A longer Retry-After fails at once and names the wait. Other statuses, such as 404, are not retried.
  • If the index still cannot be read, the install fails and names VFOX_PYTHON_USE_UV_BUILD=0. It never starts a silent source build.
  • With VFOX_PYTHON_MIRROR set and VFOX_PYTHON_UV_BUILD_MIRROR unset, CPython stays on the python.org mirror and builds from source, because uv-build downloads come from GitHub.
  • A pyenv index failure reports the HTTP status instead of a Lua concatenation error.

Design notes

  • PostInstall reads PreInstall's decision. PreInstall sets the package note to uv-build, and vfox passes the note to PostInstall in sdkInfo. PostInstall makes no second index request, so it cannot disagree with PreInstall or fail after a download. Checked with vfox 1.0.13 and 1.1.0.
  • A source build never builds over an archive. vfox clears the directory of a failed or interrupted install, so a Python already in the install path came from an archive. In that case the source build refuses to start, and the error says how to recover.
  • Partial names prefer the index. A partial name names a line, and plain requests never select a pre-release or a free-threaded build, so the newest archive on that line is a safe answer. The trade-off: while pyenv has a newer patch that the index does not list yet, python@3.12 installs the older patch the index lists. Name the exact version to build the newer one.
  • latest stays on the newest standard release. Resolving it in the index would silently install an older release while pyenv is ahead. It also skips free-threaded builds even when they are newer, as uv does by default for Python 3.13. A free-threaded build is installed only when its name asks for it.
  • One ordering for every list. The uv-build list and the pyenv list use one comparator, python_version.newer_first, so latest no longer depends on the order the index returns.
  • Index requests retry, and still fail loudly. readIndex in lib/util.lua sends a request again in the cases above, with a warning for each retry. A failure that persists is an error that names VFOX_PYTHON_USE_UV_BUILD=0; the default mode does not fall back to a source build for it.

Tests

  • vfox plugin test . with vfox 1.1.0, the version CI pins: every test file passes, including the new tests/index_retry_test.lua.
  • tests/index_retry_test.lua covers a 503, a transport error, and a 429 followed by a 500, each of which ends in success after retries; a persistent 503 or transport error stops after three attempts; a 404 is not retried; Retry-After in seconds is used in any letter case, and a value above ten seconds fails at once; an HTTP date is ignored; a 200 with an HTML page, or with JSON that lacks the list, is sent again; the pyenv index is retried too; and the Linux and Windows pause commands are checked.
  • tests/uv_build_default_test.lua and tests/uv_build_test.lua count the requests that a failing index receives.
  • New CI step, test.yml (Windows leg): a search through a closed proxy with VFOX_PYTHON_USE_UV_BUILD=1 must fail after three attempts, show two retries, and take at least three seconds. The plugin tests never sleep, so this is the only check of the real Windows wait.
  • New CI job, lint.yml docs: .github/scripts/check_docs_parity.py checks that every page has its counterpart in the other language, that both pages of a pair name the same VFOX_* variables and have the same number of fenced code blocks, and that relative links resolve.
  • Checked locally: stylua --check ., actionlint 1.7.7 on the workflows, the glua Windows installer layout test, and the docs check.
  • Real runs with this head, against the live indexes, vfox 1.1.0:
    • default mode through a closed proxy (HTTPS_PROXY=http://127.0.0.1:9): fails after about 6 s; each index is sent three times, with two warnings each, and both failures are listed.
    • VFOX_PYTHON_USE_UV_BUILD=1 through the closed proxy: fails after about 3 s, with two warnings and after 3 attempts.
    • default mode, network, fresh VFOX_HOME: about 0.9 s, no warnings, 999 entries.
    • VFOX_PYTHON_USE_UV_BUILD=1, network, fresh VFOX_HOME: about 1.5 s, no warnings, 10 entries. The real uv-build index passes the new body check.
  • Real installs from earlier heads, on the same paths: vfox 1.1.0 python@3.12 resolves to 3.12.16 and installs from the archive; vfox 1.0.13 python@3.12.16 installs from the archive; python@2.7.18, which the index lacks, falls back to a pyenv source build.

Not verified here, and known limits

  • The Windows wait is checked only by the new CI step. Until that run is green, the Windows wait is unverified.
  • The archive download belongs to vfox. The plugin cannot retry it, and vfox 1.1.0 has no setting for download retries. The docs say to run the install again.
  • An HTTP-date Retry-After is not read; the fixed wait applies instead.
  • The Chinese pages are checked for structure by CI. Their sentences were read against the English pages in this branch, but a native reviewer should still read them before merge.
  • macOS and Alpine installs did not run here; their index responses were checked over HTTP only.
  • The E2E suites are the check for real installs on this head; they run in CI.

On Linux and macOS, a CPython install now takes the prebuilt uv-build archive
when the uv-build index lists the version, and builds from source with pyenv
otherwise. Windows, GraalPy, PyPy and Conda keep their current paths.

- VFOX_PYTHON_USE_UV_BUILD is three-state: unset selects the default above,
  0/false/no/off builds every CPython from source, and 1/true/yes/on uses
  uv-build only, as before.
- Available lists the pyenv names together with the CPython releases only the
  index lists, newest first; pyenv -dev snapshots sort last.
- A partial name such as python@3.12 resolves in the index first, so it installs
  the newest 3.12 that has an archive. Only a line the index does not list falls
  back to the combined list. latest is unchanged.
- PreInstall sets the note "uv-build" on an archive. vfox passes the note to
  PostInstall in sdkInfo, so PostInstall makes no second index request. A source
  build refuses to start over a Python already in the install path.
- With VFOX_PYTHON_MIRROR set and VFOX_PYTHON_UV_BUILD_MIRROR unset, CPython stays
  on the python.org mirror and builds from source, because uv-build downloads come
  from GitHub.
- An index that cannot be read fails the install and names
  VFOX_PYTHON_USE_UV_BUILD=0; it never starts a silent source build.
- The source-build E2E subtests set VFOX_PYTHON_USE_UV_BUILD=0, and the container
  test installs the exact uv-build version.
- A pyenv index failure reports the HTTP status instead of a Lua concatenation
  error.
@linghengqian linghengqian added the enhancement New feature or request label Nov 14, 2026
latest stays the newest entry of the combined list. It is not resolved in the
uv-build index, because that would silently install an older release, or a
pre-release the index lists in place of a final one. The newest release comes
from its archive when the index lists it, and is built from source, with a line
saying so, when it does not.

Add a test for the case where pyenv lists a newer release than the index, and
document the behaviour in English and Chinese.
Bring in #61 (read Python's MSIs from the installer, drop vendored WiX).

The only textual conflict was the require list at the top of lib/util.lua.
Both requires stay: python_version (this branch) and bundle (main). The other
files merged without conflicts; the merged tree passes vfox plugin test with
vfox 1.1.0, the glua Windows layout test, stylua and go vet.
…s for latest

With VFOX_PYTHON_USE_UV_BUILD=1 the list kept the order the index returned,
and latest took its first entry, so latest depended on that order. The pyenv
list sorted names with compare_versions, which reads 3.13.18t as 3.13.0.

The uv-build list and the pyenv list now use one comparator,
python_version.newer_first: release numbers first, then a final build before
its free-threaded build before its pre-release, with snapshots last.

latest is now the first entry that is not a free-threaded build. A
free-threaded build is installed only when its name asks for it, as the README
describes, so latest never selects one. The =1 test now expects the
newest-first list, and new tests cover the comparator, the pyenv order and
latest.
The uv-build and pyenv index requests were sent once, so a brief network error,
HTTP 429 or 5xx failed a CPython install in the default mode. A transient failure
is now sent again: up to three attempts in all, with pauses of one and then two
seconds, and each retry is announced.

A failure that persists still fails the install and names
VFOX_PYTHON_USE_UV_BUILD=0. The default mode does not fall back to a source build
for it, and other statuses such as 404 are not retried.

The pause is replaced in the tests that fail an index, because os.execute is
disabled in plugin tests. tests/index_retry_test.lua covers the retries, the pause
commands on Linux and Windows, and the pyenv index. The default-mode tests count
the requests that a failing index receives.
latest selects the newest standard release even when a free-threaded build is
newer, and a free-threaded build is installed only when its name asks for it. Both
modes are tested (uv_build_test.lua and uv_build_default_test.lua); the English and
Chinese version pages now say so as well.
An index request reads the Retry-After header, in seconds, and waits for it
when it is at most ten seconds. Without a usable header it waits one second,
then two. A longer Retry-After fails at once and names the wait. HTTP-date
values are not read.

A 200 response that is not the index is sent again too. Before, an HTML page
raised a Lua error, and a JSON object without the list was read as an empty
list. The body check is inside the retry loop, so it applies to both indexes.

The reads and the waits live in readIndex in lib/util.lua. The tests cover the
Retry-After forms, the captive-portal body, the pause commands on Linux and
Windows, and the uv-build and pyenv indexes.
test.yml runs a search through a closed proxy on Windows, with
VFOX_PYTHON_USE_UV_BUILD=1. It must fail after three attempts, show two
retries, and take at least three seconds, which only happens when the
PowerShell pause runs through os.execute. The plugin tests never sleep, so
this is the only check of the real Windows wait.

lint.yml gets a docs job that runs .github/scripts/check_docs_parity.py. It
compares each Chinese page with its English page: both exist, both name the
same VFOX_* variables, both have the same number of fenced code blocks, and
every relative link resolves. Sentences are not compared; translations differ
on purpose.
The index retries, Retry-After and the archive download limit are described in
English and Chinese. The stale getIndexWithRetry references are gone.

The Chinese pages changed in this branch were read against their English
pages. The mirror paragraph now names VFOX_PYTHON_UV_BUILD_MIRROR instead of
"this mirror", and a few sentences were reworded for clarity.
The search in the Windows retry check is meant to fail. Its exit code stayed in
$LASTEXITCODE, which the runner reads, so the step failed even though every
check held: run 43580252144 waited 5.8 seconds, reported three attempts and two
retries. The step now exits 0 once its checks pass.
@linghengqian
linghengqian merged commit 1948682 into main Nov 14, 2026
12 of 13 checks passed
@linghengqian
linghengqian deleted the feat/uv-build-default branch November 14, 2026 10:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant