2026 Remote Mac Python CI: uv, PyPI Mirrors & Lockfile Pull Matrix

Use this matrix before you standardize a toolchain on shared remote Mac runners. It assumes Apple Silicon or Intel macOS build hosts and WAN pulls to PyPI or regional mirrors.

Rule of thumb for 2026 Python CI on MacPull-style nodes: if most dependencies are on PyPI and you want one lockfile plus aggressive parallel I/O, default to uv. Keep pip in thin wrapper jobs only when upstream docs mandate it.

These variables are read directly by uv (see the upstream environment reference). Tune them per link quality; raise timeouts before you raise concurrency on lossy cross-border paths.

Copy-paste block for a shell step (adjust mirror host to your approved endpoint):

export UV_CACHE_DIR="${UV_CACHE_DIR:-$HOME/Library/Caches/uv-ci}"
export UV_DEFAULT_INDEX="${UV_DEFAULT_INDEX:-https://pypi.org/simple}"
# Fallback mirror (example placeholder—replace with your org mirror):
# export UV_DEFAULT_INDEX="https://your-mirror.example.com/simple"

export UV_CONCURRENT_DOWNLOADS="${UV_CONCURRENT_DOWNLOADS:-16}"
export UV_CONCURRENT_BUILDS="${UV_CONCURRENT_BUILDS:-2}"
export UV_HTTP_TIMEOUT="${UV_HTTP_TIMEOUT:-180}"
export UV_HTTP_CONNECT_TIMEOUT="${UV_HTTP_CONNECT_TIMEOUT:-30}"
export UV_HTTP_RETRIES="${UV_HTTP_RETRIES:-8}"

uv sync --frozen --no-dev

pip-style job without a pyproject workspace:

uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt \
  --index-url "${UV_DEFAULT_INDEX:-https://pypi.org/simple}"

Symptoms cluster into three buckets: handshake failures, MITM corporate roots, and proxy routing loops. Fix certificate trust first; only then chase higher UV_HTTP_RETRIES.

export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal,private-index.example.com"
# Optional: enterprise PEM
export SSL_CERT_FILE="/etc/ssl/certs/org-bundle.pem"

For shared-runner contention patterns (not Python-specific), see pull stability FAQ and the Rust mirror/retry matrix—the same retry mindset applies across ecosystems.

Reproducibility is a contract between resolver inputs and the committed graph. On remote Mac CI, separate resolve/fetch from test so flaky WAN shows up early.

# Job A: fetch + install only
uv sync --frozen --no-dev
# Job B: tests assume env is warm
uv run pytest -q

Cache pollution. Share one UV_CACHE_DIR per stable runner image key, or namespace by team. Schedule uv cache prune when disk crosses your watermark; combine with the concurrency guidance in build pool disk FAQ.

Platform wheels. Apple Silicon resolves macosx_11_0_arm64 tags; Intel runners need different wheels. If you generate locks on the wrong arch, CI rebuilds sdists or fails. Align runner architecture or use explicit platform flags when locking for heterogeneous pools.

Private + public PyPI. Put the private Simple API on UV_DEFAULT_INDEX when it should win, add PyPI through UV_INDEX or tool.uv.index entries, and avoid unsafe-best-match unless you understand cross-index version competition. Authenticate with UV_INDEX_{NAME}_USERNAME / UV_INDEX_{NAME}_PASSWORD for named indexes.

Pick uv when PyPI throughput and lockfile speed matter on a remote Mac; drive mirrors through UV_DEFAULT_INDEX and friends; raise UV_HTTP_TIMEOUT and UV_HTTP_RETRIES before you chase ever-higher UV_CONCURRENT_DOWNLOADS. Commit uv.lock and run uv sync --frozen in CI for deterministic installs.

When you need Apple Silicon close to your users with stable egress for large pulls, browse MacPull pricing and help & getting started—both are readable without logging in. Choose a node size that matches your parallel build+download footprint; oversized concurrency on a small VM only amplifies timeouts.