Technology handbook
uv package manager
Python projects, interpreters, dependencies, tools, workspaces, builds and reproducible automation.
- Topics
- 30
- Sections
- 4
uv projects
uv init
Create an application or library project and inspect its pyproject.toml before adding dependencies.
- An application layout gets a main module; a library layout gets a package and a build backend.
- The generated manifest already carries the name, version and Python requirement.
- Nothing is installed yet, so the first run or sync creates the environment.
pyproject.toml
Declare metadata, Python requirements, dependencies and tool configuration in the project's standard manifest.
- One file holds metadata, the Python requirement and the dependency lists.
- Tool sections let formatters, linters and type checkers share the same manifest.
- Hand edits are legitimate, but the lockfile must be refreshed after them.
uv add and remove
Update declared dependencies and the resolution together instead of manually editing an environment.
- Adding a package writes the manifest, updates the lock and installs in one step.
- A version specifier given at add time is recorded rather than pinned silently.
- Removing takes the entry out of the manifest and drops what nothing else needs.
uv run
Run a command in the project environment with automatic synchronization unless explicitly disabled.
- The command runs against the project environment without activating it first.
- uv checks the lock and syncs beforehand unless it is told not to.
- It is what makes a checked-out repository runnable with no setup steps.
uv sync
Synchronize installed packages to the project resolution; exact sync can remove undeclared packages.
- Sync makes the environment match the lockfile exactly, install and uninstall alike.
- A package installed by hand is removed, which is what makes the result reproducible.
- Group and extra flags decide which optional dependencies are included.
uv lock
Resolve dependency versions without confusing the lockfile with an installed environment.
- Locking resolves versions for every supported platform, not just the current one.
- The lockfile is committed, so a colleague and CI resolve to the same versions.
- Resolution on its own changes nothing that is installed on the machine.
uv tree
Inspect direct and transitive dependencies to diagnose unexpected packages or conflicts.
- The tree shows which package pulled in a transitive dependency you did not expect.
- It reports version conflicts alongside the requirement that forced each choice.
- Reading it is the fastest way to find why a resolution is pinned low.
Dependency groups and extras
Separate development groups from optional features that consumers may request.
- A development group is for contributors and never ships to consumers.
- An extra is an opt-in feature a consumer requests by name at install time.
- Putting test tooling in an extra exposes it as a public part of the package.
Python environments
Python installation
Install supported Python interpreters and distinguish managed interpreters from system installations.
- uv can download and manage interpreters independently of the system package manager.
- A managed interpreter is standalone, so an operating system upgrade cannot disturb it.
- Pointing at a system interpreter stays possible when a project requires it.
Python version pinning
Record a project interpreter preference and keep it compatible with requires-python.
- A pinned version file records which interpreter the project expects locally.
- The pin must satisfy the manifest requirement or commands refuse to run.
- Pinning an exact patch release is usually stricter than a project actually needs.
Virtual environments
Isolate installed distributions and choose the interpreter before creating an environment.
- The environment lives in the project directory and is disposable by design.
- Choose the interpreter at creation time, because it cannot be changed afterwards.
- Deleting the directory and syncing again is a legitimate repair.
uv pip install
Use uv's pip-compatible interface when managing an environment outside the project workflow.
- The pip-compatible surface helps when migrating an existing workflow gradually.
- It installs into the environment without touching the manifest or the lockfile.
- Anything installed this way disappears at the next exact sync.
uv pip compile and sync
Resolve requirements files and synchronize a compatible environment from their pinned output.
- Compiling turns a loose requirements file into a fully pinned one.
- Pin per target platform, since one file cannot describe every environment.
- This path suits deployment tooling that cannot read the project lockfile.
Platform markers
Declare dependencies that apply only to specific Python versions or operating systems.
- A marker attaches a dependency to a Python version or an operating system.
- Markers are evaluated at install time, so one lockfile covers several targets.
- They keep a Windows-only or GPU-only package out of environments that cannot use it.
Resolution & workspaces
Locked versus frozen
Use --locked to reject manifest drift; --frozen skips checking whether the lock matches current metadata.
- Freshness checking fails the command when the lock no longer matches the manifest.
- Skipping that check installs the lock as it stands, drift included.
- CI wants the checking form, so a stale lock is caught in review rather than production.
Dependency upgrades
Upgrade selected dependencies deliberately and review transitive changes in the lockfile.
- Upgrade one package at a time so a regression has an obvious cause.
- The lockfile diff shows the transitive moves the upgrade dragged along.
- A full re-resolution is a separate, deliberate change rather than a side effect.
Constraints and overrides
Distinguish restricting allowed versions from replacing a dependency's declared requirement.
- A constraint narrows the versions the resolver may pick but adds no dependency.
- An override replaces what a package declares, which can produce an unsupported combination.
- Reach for an override only to work around a wrong upstream pin, and record why.
Package indexes
Configure index priority and authentication without enabling dependency-confusion paths.
- Index order decides which source wins when a name exists in more than one.
- An unpinned private name on a public index is the dependency-confusion risk.
- Keep credentials in the environment or a keyring rather than in the manifest.
Git and path dependencies
Reference a source revision or local package with an explicit reproducibility strategy.
- A git dependency should name a tag or a commit, never a moving branch.
- A path dependency is for a sibling package in the same checkout.
- Neither is reproducible for consumers once the package is published.
Workspace members
Resolve a multi-package workspace together while choosing which member to run or sync.
- A workspace resolves every member together against one shared lockfile.
- Members depend on each other by name and pick up local changes immediately.
- Commands take a package flag to sync or run inside one member.
Editable installations
Use editable source during development and verify the built distribution separately.
- An editable install points at the source tree, so edits take effect without reinstalling.
- It hides packaging mistakes, because files outside the distribution still import.
- Build a wheel and install it once before release to check what is actually shipped.
Lockfile export
Export a supported format when another deployment tool cannot consume uv.lock directly.
- Export produces a requirements file for a platform that cannot read the lock.
- The export is generated output and belongs in the build, not in the repository.
- It flattens the resolution, so the markers and hashes it keeps matter.
Sources
- uv package manager official documentation