Add optional uv backend (opt-in via --use-uv / config)

[gilgamezh]

What

Adds uv as an opt-in backend for venv creation and dependency installs. By default fades keeps using venv/pip; uv is used only when explicitly requested. Everything else (dependency parsing, venv indexing/cache, GC, --where/--rm, REPL/autoimport, config files) is unchanged.

Closes #451.

Enabling uv

• --use-uv — use uv for this run.
• --uv-path PATH — point at a specific uv executable (implies --use-uv); otherwise uv is looked up in PATH and validated. If uv is requested but not found, fades errors out.
• use_uv=true in any fades config file (/etc/fades/fades.ini, the per-user fades.ini, or a repo-local ./.fades.ini) enables it permanently; a CLI flag still wins.

Design notes

• Opt-in, not auto-detect (per discussion in Proposal: support uv as an optional backend for venv creation & installs #451): uv produces different venv contents than pip, so fades' behaviour shouldn't change merely because uv is installed.
• uv has no Python API (Non-CLI usage of uv? (From existing Rust code, or possibly from Python) astral-sh/uv#6080 closed without one), so it's invoked via subprocess like the existing PipManager. fades does not depend on the uv PyPI package (it runs against the system Python); it uses a uv binary on PATH.
• UvManager mirrors PipManager's install/get_version, dispatched from envbuilder.create_venv. Backend resolution + option validation live in main._resolve_uv_backend (unit-tested).
• uv venv --seed so the venv ships pip (and setuptools, per Python version) like the classic backend.
• When uv is used: the PyPI availability pre-check is skipped (uv resolves directly); --pip-options/--venv-options are errors (use --uv-pip-options); --freeze uses plain pip freeze on the seeded venv.

Tests / CI

• Unit tests for _resolve_uv_backend (enabled/disabled, --uv-path, not-found, option conflicts), UvManager, envbuilder dispatch, get_uv_exe.
• Integration jobs (archlinux/fedora/native-windows) exercise: default = pip, --use-uv = uv, conflict + bogus-path errors, and --freeze on a uv venv. Windows confirms the uv path end-to-end.

🤖 Generated with Claude Code

[gilgamezh]

Benchmark: uv vs pip

Wall time for fades -d <pkg> -x <run-something-in-the-venv>, comparing the default (uv) backend against --no-uv (pip).

django (single dependency)

Scenario	Backend	Wall time
Fresh venv (create + install)	pip (--no-uv)	3.43s
Fresh venv (create + install)	uv	0.39s
Existing/cached venv (no install)	either	~0.16s

≈ 8.7× faster on the create+install path.

jupyterlab (~60 transitive deps)

Scenario	Backend	Wall time
Fresh, cold package cache (incl. downloads)	pip (--no-uv)	16.63s
Fresh, cold package cache (incl. downloads)	uv	12.70s
Fresh, warm package cache (already downloaded)	pip (--no-uv)	13.97s
Fresh, warm package cache (already downloaded)	uv	1.62s
Existing/cached venv (no install)	either	0.92s

• Cold cache (first-ever install): ≈ 1.3×. On a first install both backends spend most of the time downloading the same ~60 wheels over the network, which dominates and masks the backend difference.
• Warm cache (steady state, packages already fetched once): 13.97s → 1.62s ≈ 8.6× faster — this isolates uv's actual resolve+install speed and matches the django ratio.

Takeaways

• uv is ~8–9× faster on the install itself; the small cold-cache jupyterlab number is just because raw download bandwidth (identical for both backends) dominates the very first run.
• The cached-venv path is unchanged regardless of backend — no install happens, fades just reuses the venv.

Single run per row, warm/cold as noted; numbers will vary with network and machine.

[gilgamezh]

uv venvs now seed pip/setuptools (uv venv --seed) + a note on pkg_resources

While testing azure-cli we hit ModuleNotFoundError: No module named 'pkg_resources' on the uv backend, which surfaced two separate things:

1. uv venvs were missing pip/setuptools (fixed)

uv venv seeds nothing by default, whereas the classic python -m venv backend ships pip (and, on Python ≤ 3.11, setuptools). So uv-built venvs silently lacked tooling that some packages expect to be present. fades now runs uv venv --seed, restoring that parity:

• Python 3.12+: seeds pip (matches stdlib venv, which dropped setuptools seeding in 3.12).
• Python ≤ 3.11: seeds pip + setuptools.

Cost is negligible (~6 ms, warm cache).

2. pkg_resources / azure-cli (not fixable transparently — documented)

azure-cli imports the long-deprecated pkg_resources, which setuptools removed in >= 81. --seed installs a recent setuptools, so it does not bring pkg_resources back. Importantly, this is not uv-specific — the pip backend fails the same way on Python 3.12+ (no setuptools seeded at all). It only "works" on the classic backend on Python ≤ 3.11 because that seeds an old bundled setuptools that still ships pkg_resources.

fades shouldn't force-pin an old setuptools, so the workaround is documented in the README — request an older setuptools explicitly:

fades -d azure-cli -d "setuptools<81" -x az --help

(or --no-uv on a Python old enough to seed an old setuptools). Verified this restores pkg_resources (setuptools 80.10.2) through the uv backend.

Implemented in 9ab2790.

[gilgamezh]

Switched uv from default to opt-in

Following the discussion in #451 (thanks @facundobatista), uv is no longer auto-detected/used when present. It's now explicit:

• --use-uv (or --uv-path) per run, or use_uv=true in a config file (machine/user/repo .fades.ini) to enable it always — CLI overrides config.
• requesting uv when it isn't installed is an error (no silent fallback).
• --pip-options/--venv-options are rejected with uv; use the new --uv-pip-options for uv pip install passthrough.
• the PyPI pre-check is skipped under uv; --freeze uses standard pip-freeze output (venvs are seeded with pip).

The FADES_USE_UV env var idea was dropped in favor of config files, which already support per-repo/per-machine scoping plus CLI override. The README documents a one-liner to flip use_uv=true into your fades.ini.

All green on Linux/macOS/Windows.