Uv Knowledge Patch

uv Knowledge Patch

Use this guidance for uv-managed Python projects, environments, dependency resolution, package indexes, publishing, tools, CI, and containers. Inspect the repository and installed executable before changing a workflow: project files, lockfiles, and observed behavior take precedence when they differ from this guidance.

Working Method

1. Run uv self version to identify the uv executable. uv version reads or changes a project's version and errors outside a project.
2. Inspect pyproject.toml, uv.toml, .python-version, uv.lock, relevant pylock*.toml files, inline-script metadata, and CI or container files.
3. Decide whether each proposed command is stable or preview. Keep preview behavior explicit in durable scripts and configuration.
4. Read the task-specific reference from the index before choosing flags or settings.
5. Preserve lockfile intent. Use uv lock --check or --locked to verify; reserve uv lock --refresh for deliberate canonical regeneration.
6. Treat credential changes, certificate overrides, publishing, environment replacement, archive validation bypasses, and malware checks as sensitive.

Reference Index

Breaking Changes and Compatibility Traps

Distinguish executable and project versions

Use uv self version for the executable. Inside a project, uv version reads or updates project metadata and can lock and sync after an update; it is not a fallback executable-version command.

Expect packaged initialization

uv init <name> creates a uv_build-backed src/<name> package, project script, and installed project. Use --no-package for the former unpackaged main.py layout. Existing projects do not change automatically, and a pinned uv_build range must admit the version used by newly initialized projects.

Preserve lockfile formatting and state

uv lock --check and --locked reject non-canonical uv.lock formatting. Regenerate intentionally with uv lock --refresh. Check commands return 1 for stale state and reserve 2 for operational errors. --isolated must not rewrite the project lockfile.

Account for stricter validation

Treat these as errors rather than ignored input:

• nonexistent local extras;
• missing frozen dependency groups and unknown group object specifiers;
• --frozen combined with --no-sources;
• unmatched project.license-files globs or non-UTF-8 license files;
• malformed or unsafe archives and invalid pylock.toml structure;
• hash-checking requirements that are unpinned, unhashed, or MD5-only.

Arbitrary executable names in .python-version are ignored. uv_build rejects invalid classifiers and warns on legacy license classifiers.

Treat index failures as authoritative

The default first-index strategy stops on 401 or 403. Use ignore-error-codes only for an index whose unusual behavior requires fallthrough. authenticate = "always" makes missing credentials fail closed. Only one index may be default = true, and an explicit index needs a name.

Do not rely on certificate fallback

An explicitly set SSL_CERT_FILE or SSL_CERT_DIR is authoritative. If it is missing, inaccessible, empty, or contains no certificates, fix or remove it; uv does not silently fall back to default trust roots.

Revisit Python and platform assumptions

Unversioned installation and automatic download now prefer Python 3.14. Discovery can select a free-threaded 3.14+ interpreter without a t suffix, while installation still prefers a GIL-enabled build. The linux platform alias means manylinux_2_28; request x86_64-manylinux_2_17 explicitly when that older target is required.

Pin container and formatter behavior

Floating images now follow Debian 13 Trixie and Alpine 3.22; removed tags include Bookworm, Alpine 3.21, and Python 3.8. Preview uv format moved to Ruff 0.15 and the 2026 style guide. Pin the image tag and formatter version when reproducibility matters.

High-Value Workflows

Verify lockfiles and environments

uv lock --check
uv sync --check
uv lock --refresh

Use the first two commands for CI verification. Run the refresh command only when rewriting the lockfile is the intended repository change.

Check projects and workspaces

uv check --package my-package
uv check --all-packages
uv workspace list --paths
uv workspace dir

Package selection for uv check is preview. Workspace listing and directory discovery are stable scripting interfaces. uv workspace metadata includes best-effort active-environment data by default, so its output can vary with the invocation environment.

Preview checks also provide --fix, --no-install-project, and explicit --script. Scripts are not checked unless requested. uv tool audit can inspect installed tools, and configured malware checks can screen locked tools before cache reuse.

Control resolution precisely

• Apply build constraints to project builds, uv run --with, tools, and inline scripts.
• Use per-group Python requirements and default-groups = "all" deliberately.
• Require wheel coverage with tool.uv.required-environments.
• Prefer package-specific cutoffs, dependency exclusions, selective --no-sources-package, and stable bounds controls over broad workarounds.
• Use marker-aware uv upgrade when repeated declarations differ by markers.
• Override automatic stable-then-prerelease fallback with an explicit global or package-specific prerelease policy when the distinction matters.

Exchange standardized results

Generate, compile, install, and sync PEP 751 files named pylock.toml or pylock.<name>.toml. A valid file contains a packages array, which may be empty, and declared artifact sizes are checked.

CycloneDX exports include distribution artifact URLs and hashes. Preview JSON sync output can describe package changes made by the operation.

Select indexes and credentials explicitly

[[tool.uv.index]]
name = "private"
url = "https://packages.example.invalid/simple"
authenticate = "always"

Named flat indexes share the same configuration. Under preview index-by-name, --index and --default-index may select a configured name; preview index configuration can also choose the lockfile hash algorithm. When several credentials match a URL, supply the username explicitly.

Install and discover Python deliberately

UV_PYTHON takes precedence over .python-version for uv python install. Managed installs add versioned executables to a PATH directory and can register with the Windows launcher; use --no-bin or --no-registry to suppress those effects. Changing managed/unmanaged discovery preference can invalidate and recreate the project environment.

Run tools and temporary requirements safely

uvx <name> verifies that the requested executable comes from that package or its dependencies. Use uvx --from <package> <command> when the package and command intentionally differ. uv run --with executes through a fresh empty top layer over a cached requirement environment, so runtime mutations do not modify the cached layer.

Protect virtual environments

Interactive uv venv prompts before clearing an existing virtual environment and refuses to remove a non-environment directory. State the decision with --clear or --no-clear. Preview relocatable environments omit activate.csh; a .venv file may instead point to a centralized environment.

Audit, format, and publish cautiously

uv audit and uv format are preview commands. Auditing batches OSV queries and supports linked findings and report formats. Publishing supports stored credentials, PEP 740 attestations, Trusted Publishing with pyx, and preview S3 or GCS signing flows. Validate archives and authentication before upload.

Final Checks

• Confirm stable versus preview status for each durable command.
• Re-run lock and environment checks after dependency or version changes.
• Test the intended implementation, GIL mode, and target platform explicitly.
• Verify index names, authentication policy, username, proxy, certificate, and upload timeout settings before diagnosing resolution or publishing failures.
• Pin formatter behavior and container tags where reproducibility matters.
• Inspect the relevant reference before changing security, publishing, environment-clearing, lockfile, or archive-validation behavior.