astral-sh/uv

Every user-facing verb is a clap variant on Commands in crates/uv-cli/src/lib.rs and is matched in crates/uv/src/lib.rs. Project commands (init, add, remove, lock, sync, run, tree, export, version, upgrade, format, check, audit) manage pyproject.toml workspaces and PEP 723 scripts. The pip namespace is a compatible interface for compile, sync, install, uninstall, freeze, list, show, tree, and check. Separate namespaces cover Python installs, pipx-like tools, publishing, authentication, the cache, workspaces, and a hidden PEP 517 build-backend shim. Many newer commands are gated by PreviewFeature flags and warn until --preview-features or UV_PREVIEW is set.

• Top-level Commands are Auth, flattened Project, Tool, Python, Pip, Venv (aliases virtualenv and v), Build, Publish, Workspace, hidden BuildBackend, Cache, Self_, hidden Clean, hidden GenerateShellCompletion, and Help. Global flags include --config-file (UV_CONFIG_FILE), --no-config (UV_NO_CONFIG), and -V.
  crates/uv-cli/src/lib.rs#L130-L185crates/uv-cli/src/lib.rs#L451-L614
• ProjectCommand covers Run, Init, Add, Remove, Version, Sync, Lock, Upgrade, Export, Tree, Format, Check, and Audit. uv run treats .py files and HTTP(S) URLs as scripts, reads PEP 723 inline metadata, and syncs the project environment before invoking the command. uv add and uv lock can create a PEP 723 tag; other --script commands require one already.
  crates/uv-cli/src/lib.rs#L1089-L1120crates/uv/src/lib.rs#L363-L422
• PipCommand implements compile, sync, install, uninstall, freeze, list (alias ls), show, tree, check, and a hidden debug command. pip compile writes requirements.txt or pylock.toml; pip sync removes packages not listed in the input file. If the user types uv install or uv compile, suggest_subcommand rewrites the hint to uv pip install or uv pip compile.
  crates/uv-cli/src/lib.rs#L1018-L1086crates/uv/src/lib.rs#L2961-L3003
• PythonCommand is list, install, upgrade, find, and pin. Install docs state CPython comes from Astral python-build-standalone and PyPy from python.org, with the version catalog bundled in each uv release. pin writes .python-version. Discovery order is documented on the Python command: active or .venv interpreter, then PATH, then the Windows registry, with automatic downloads unless --no-python-downloads or python-downloads disables them.
  crates/uv-cli/src/lib.rs#L470-L517crates/uv-cli/src/lib.rs#L6112-L6180
• python install is implemented by commands::python::install::install, which locks ManagedPythonInstallations, resolves targets, downloads in perform_install, and optionally bytecode-compiles the stdlib. --default is experimental unless PreviewFeature::PythonInstallDefault is enabled.
  crates/uv/src/commands/python/install.rs#L201-L272crates/uv/src/commands/python/install.rs#L309-L352
• ToolCommand is run, a hidden uvx alias, install, upgrade, list, audit, uninstall, update-shell (alias ensurepath), and dir. uvx and uv tool run are documented as identical. Tools install into an isolated environment under the XDG tools directory; uv tool run uses an ephemeral environment in the cache unless an installed tool is reused.
  crates/uv-cli/src/lib.rs#L5441-L5517crates/uv/src/bin/uvx.rs#L81-L86
• AuthCommand is login, logout, token, dir, and a hidden helper. The helper implements the Bazel credential-helper protocol over JSON on stdin/stdout and is the only AuthHelperProtocol variant. Credentials live in $XDG_DATA_HOME/uv/credentials or $HOME/.local/share/uv/credentials on Unix and %APPDATA%\uv\data\credentials on Windows, overridable with UV_CREDENTIALS_DIR. The native keyring backend is separate from that directory.
  crates/uv-cli/src/lib.rs#L5406-L5431crates/uv/src/lib.rs#L639-L692
• CacheCommand is clean (alias clear), prune (--ci drops prebuilt wheels but keeps wheels built from source), dir, and size. The default cache path documented in the CLI is $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Unix and %LOCALAPPDATA%\uv\cache on Windows, overridable by cache-dir, --cache-dir, or UV_CACHE_DIR. --no-cache uses a temporary directory discarded at process exit.
  crates/uv-cli/src/lib.rs#L922-L948docs/concepts/cache.md#L24-L39
• uv publish uploads files through uv_publish::PublishSession. It refuses offline mode, can select an index by name and that index's publish_url, and accepts username, password, TrustedPublishing, keyring_provider, check_url, dry_run, and no_attestations.
  crates/uv/src/commands/publish.rs#L28-L80
• BuildBackendCommand is hidden and implements the PEP 517 and PEP 660 hooks: build_sdist, build_wheel, build_editable, get_requires_for_build_sdist, get_requires_for_build_wheel, prepare_metadata_for_build_wheel, get_requires_for_build_editable, and prepare_metadata_for_build_editable. The separate uv-build binary dispatches build-sdist without clap.
  crates/uv-cli/src/lib.rs#L575-L583crates/uv-cli/src/lib.rs#L7929-L7957crates/uv-build/src/main.rs#L17-L80
• WorkspaceCommand (mostly preview) is metadata, dir, and list. metadata can target a PEP 723 script and supports --locked (UV_LOCKED) and --frozen (UV_FROZEN). SelfCommand is update and version. Self update accepts an optional target version, UV_GITHUB_TOKEN, and --dry-run.
  crates/uv-cli/src/lib.rs#L7812-L7852crates/uv-cli/src/lib.rs#L885-L912
• PreviewFeature is a u64 bitflags enum. Flags that gate user-visible behavior include PythonInstallDefault, JsonOutput, Pylock, FormatCommand, NativeAuth, CacheSize, SbomExport, AuthHelper, AuditCommand, MalwareCheck, CheckCommand, PackagedInit, CentralizedProjectEnvs, ToolInstallLocks, and LockWithoutMetadata. Unknown names parse as MaybePreviewFeature::Unknown.
  crates/uv-preview/src/lib.rs#L230-L347crates/uv-preview/src/lib.rs#L375-L378
• Output formats exposed on the CLI include VersionFormat and SyncFormat (text or json), AuditOutputFormat (text, json, sarif), CacheSizeOutputFormat (auto, human, machine), TreeFormat (text or json), and ListFormat (columns, freeze, json).
  crates/uv-cli/src/lib.rs#L45-L112