CodeVetter · Repo Unpack · Data flow
astral-sh/uv
User input enters as CLI arguments, environment variables, and config files, and is merged into typed settings before any network call. Project metadata is discovered from pyproject.toml workspaces or PEP 723 scripts, lowered into requirements, and solved against PEP 503/691 index metadata. The solver output becomes a uv.lock (version 1) which later commands treat as the source of installable pins. Artifacts are fetched into named cache buckets and linked into a virtual environment. Credentials are attached by HTTP middleware and must not be copied into new URLs, logs, or cache keys.
- Documented configuration search reads a pyproject.toml [tool.uv] table or a uv.toml in the current directory or the nearest parent. In a workspace the search starts at the workspace root and member config is ignored. tool commands skip local files and read only user config (for example ~/.config/uv/uv.toml) and system config (for example /etc/uv/uv.toml).
- run() merges filesystem options in this order: an explicit --config-file (FilesystemOptions::from_file), or none when UV_NO_CONFIG or isolated mode is set. Tool and self commands use FilesystemOptions::user combined with system only. Otherwise Workspace::discover then FilesystemOptions::find(workspace.install_path()) is combined with user and then system. A pyproject.toml passed as --config-file warns; --project is the supported switch.
- Combine prefers the left-hand options, matching Cargo's layered config except that higher-precedence array items are placed earlier. Implemented for FilesystemOptions, Options, PipOptions, and AuditOptions in uv-settings.
- Environment variables consumed by clap and settings include UV_CACHE_DIR, UV_NO_CACHE, UV_PYTHON, UV_PYTHON_DOWNLOADS, UV_PYTHON_PREFERENCE, UV_INDEX, UV_DEFAULT_INDEX, UV_INDEX_URL, UV_EXTRA_INDEX_URL, UV_FIND_LINKS, UV_LINK_MODE, UV_KEYRING_PROVIDER, UV_NATIVE_TLS, UV_SYSTEM_CERTS, UV_REQUIRE_HASHES, UV_LOCKED, UV_FROZEN, UV_NO_CONFIG, UV_CONFIG_FILE, UV_CREDENTIALS_DIR, and UV_OFFLINE. They are constants on uv_static::EnvVars.
- Index metadata is fetched by RegistryClient::simple_detail, which implements PEP 503 and PEP 691. --no-index returns ErrorKind::NoIndex. IndexStrategy::FirstIndex queries indexes serially; each hit is simple_detail_single_index, which uses fetch_remote_simple_detail or fetch_local_simple_detail. Responses are cached as rkyv under the Simple bucket.
- Resolution output is stored as Lock. The on-disk major version constant is VERSION = 1. A uv version supports a single major version; revision changes stay readable by older uv versions that share that major. Lock::from_toml parses the file and Lock::to_toml serializes it. Export paths in uv-lock include requirements.txt, pylock.toml, and CycloneDX JSON.
- do_lock lowers requirements, overrides, constraints, and dependency groups through LockTarget::lower, builds preferences and fork markers from an existing lock, calls pip::operations::resolve, then Lock::from_resolution. Unchanged locks are detected by equality or by comparing to_toml text when format checking is on. commit writes the TOML to the lock path with fs_err::tokio::write.
- pip::operations::resolve partitions named and unnamed requirements, resolves unnamed ones with NamedRequirementsResolver, then constructs Resolver::new and awaits Resolver::resolve. Resolver::resolve runs a metadata fetcher and spawns a thread named uv-resolver whose solve method initializes a PubGrub State.
- Installation uses pip::operations::install, which builds an InstallationPlan from the resolution and SitePackages, then plan.execute. LinkMode is clone (copy-on-write, serde alias reflink) by default on macOS and Linux, and hardlink elsewhere. Other modes are copy and symlink, selected by UV_LINK_MODE.
- Cache buckets and current directory names include SourceDistributions sdists-v9, Wheels wheels-v6, Simple simple-v25, FlatIndex flat-index-v5, Git git-v0, Interpreter interpreter-v4, Archive archive-v0, Files files-v0, Builds builds-v0, Environments environments-v2, Python python-v0, Binaries binaries-v0, and Osv osv-v0. Wheels and sdists are keyed by origin (pypi, index digest, git, or URL).
- Credentials are Credentials::Basic or Bearer. TextCredentialStore persists them as credentials.toml under UV_CREDENTIALS_DIR or StateBucket::Credentials, guarded by an exclusive credentials.toml.lock. AuthBackend::from_settings uses KeyringProvider::native only when PreviewFeature::NativeAuth is enabled; otherwise it uses the plaintext store. AuthMiddleware can attach a keyring provider, indexes, and an only_authenticated flag.
- Managed CPython downloads use the prefix https://github.com/astral-sh/python-build-standalone/releases/download/ unless an Astral mirror base is appended with /github/python-build-standalone/releases/download/. ManagedPythonDownload carries a url and an optional sha256. The download catalog can be overridden with python_downloads_json_url.