One Rust binary that replaces pip, pipx, pyenv, poetry, virtualenv & pip-tools. For a project, three files stay in lockstep: pyproject.toml declares what you want, uv.lock pins the exact resolved versions, and .venv holds what's installed. Every command — add, run, sync — keeps all three honest for you.
Verified 2026-08-26 against uv 0.12.6 (installed & run) · every command from uv --help, every workflow confirmed by execution — init→add→run, the generated uv.lock, PEP 723 scripts, tools & the pip interface all run live. Structure follows the official docs.astral.sh/uv feature map.
uv init myapp && cd myapp # scaffold uv add httpx "pytest" --dev # deps + dev group uv run python main.py # auto-syncs, runs uv run pytest # in the locked env uv lock --upgrade # bump the lockfile uv sync # reproduce it exactly # commit pyproject.toml + uv.lock
uv init --script fetch.py # add header uv add --script fetch.py rich # pin dep # fetch.py now starts with: # /// script # requires-python = ">=3.12" # dependencies = ["rich>=13"] # /// uv run fetch.py # ephemeral env, just works uvx ruff check . # a tool, no install needed
curl -LsSf https://astral.sh/uv/install.sh | sh★powershell -c "irm https://astral.sh/uv/install.ps1 | iex"pip install uv · brew install uvuv self update★uv --version · uv helpuv init myapp★pyproject.toml, main.py, README.md, .python-version, git.uv inituv init --lib mylib★uv init --app · --packageuv init --barepyproject.toml — no sample files, no README, no VCS.uv init --python 3.13uv add httpx★pyproject.toml + uv.lock, install into .venv — all at once.uv add "httpx>=0.27,<1"uv add --dev pytest ruff★dev group under [dependency-groups] — not shipped to users.uv add --group docs sphinx--optional NAME for an extra instead.uv add --editable ../mylib--git URL, --branch, --tag.uv add --bounds major httpx>=0.28,<1.0 style bounds.uv remove httpx★--dev/--group to target a group.uv run python main.py★uv run pytest · uv run ruff check★uv run -- flask run -p 3000-- so flags reach your command, not uv.uv run --with rich script.py★uv run --no-sync pythonuv run --env-file .env python app.pyuv lock★uv.lock without installing.uv lock --upgrade★--upgrade-package httpx for just one.uv sync★.venv exactly match uv.lock — installs missing, removes extra.uv sync --frozen★uv sync --lockedpyproject drifted.uv sync --all-extras --all-groups--no-dev to exclude dev.uv lock --checkuv tree★--depth 1, --package httpx to focus.uv tree --invertuv export --format requirements-txt -o requirements.txt★requirements.txt from the lock (with hashes).uv export --no-hashes --no-devuv version · uv version --bump minorpyproject.toml★uv add.uv.lock★.venv/★.python-versionuv python pin.[tool.uv] in pyproject.toml[tool.uv.sources], index URLs, resolution knobs.uv run script.py★uv init --script app.pyuv add --script app.py rich "httpx>=0.27"★uv run --with pandas -- script.pyuv run --python 3.11 script.py# /// script ... # dependencies = [...] # ///uvx ruff check .★uvx = uv tool run. Runs a CLI in a cached, ephemeral env — nothing installed.uvx --from httpie http GET example.comuvx ruff@0.6.0 checkuv tool install ruff★PATH — persists across shells.uv tool list · upgrade --all · uninstall ruffuv tool upgrade --all bumps everything.uv tool update-shellPATH if it isn't already.uv python install 3.12 3.13★uv python list★--only-installed to filter.uv python pin 3.13★.python-version so this project uses 3.13.uv python install 3.13tt suffix.uv python find · upgrade · uninstalluv run --python 3.11 ...--python; uv fetches on demand.uv cache clean · prune★uv cache dir · sizeuv auth login · token · logoutuv self updateuv python dir · uv tool diruv venv★.venv in milliseconds. replaces python -m venv.venvuv venv --python 3.12uv venv myenv.venv.source .venv/bin/activateuv run/uv pip you rarely need to activate at all.uv venv --seeduv pip install httpx★.venv env.pipuv pip install -r requirements.txt★-e . for editable installs too.uv pip sync requirements.txtuv pip list · freeze · show httpxuv pip tree for the graph.uv pip checkuv pip is NOT the project APIpyproject.toml or uv.lock. Use uv add for projects.uv pip compile requirements.in -o requirements.txt★uv pip compile --universal ...★uv pip compile --upgradeuv pip compile pyproject.tomluv pip compile --generate-hashesuv build★dist/. --wheel or --sdist for just one.uv publish★dist/* to PyPI. --index / --publish-url for others.twineuv publish --token $PYPI_TOKEN[build-system] → uv_builduv build --all-packages[tool.uv.workspace] members = ["packages/*"]★uv.lock — consistent versions across all.uv syncuv run --package api uvicorn app:appuv add --package api httpx[tool.uv.sources] mylib = {workspace = true}[tool.uv.sources] mylib = {git = "https://..."}★[[tool.uv.index]] url = "https://..."explicit = true.uv add torch --index pytorch=https://...UV_INDEX_... --default-indexuv add --no-sources ...[tool.uv.sources] — resolve as a published package would.UV_PYTHON=3.12 · UV_PROJECT_ENVIRONMENTUV_PYTHON_DOWNLOADS=never★UV_CACHE_DIR · UV_NO_CACHE=1uv.toml or [tool.uv]pyproject.toml, or a standalone uv.toml.--offline · --refresh · --no-cache--exclude-newer 2026-01-01uv pip install won't update pyprojectuv add. uv pip is the low-level escape hatch.commit uv.lock, ignore .venv★sync.don't hand-edit uv.lockpyproject.toml then uv lock. Manual edits get overwritten.uv ignores an active VIRTUAL_ENV in projects.venv. Use --active to target the activated one.CI: use --frozen (or --locked)★uv is pre-1.0Resolved 8 packages in 345msPrepared 7 packagesInstalled 7 packages in 9ms.venv+ httpx==0.28.1+ added · - removed · ~ changedAudited 8 packagesUsing CPython 3.12.3Which command to reach for, why the lockfile matters, how the cache makes installs near-instant, and which classic tool each uv command retires — all drawn from behaviour verified against uv 0.12.6.
The single most common confusion. uv add is the project API and touches all three files; uv pip install is a low-level env tool that touches none of them.
pyproject says what you'll accept; the lock records what you actually got. That gap is the whole point — loose specs resolve to exact, shared versions.
uv downloads and builds each package once into a global cache, then hard-links it into every project's .venv. The second project pays almost nothing.
uv folds a whole toolbox into a single binary. Each classic command maps to a uv equivalent — usually faster and with a shared cache.
pyproject.toml + uv.lock + .venv, kept in sync.venvuv add in projects; uv pip only for raw envsuv run / uv pip target .venv directlyuvx ruff runs without installing anythinguv sync --frozen — deterministic, no re-resolveuv lock --upgrade (or --upgrade-package X)uv add --script f.py dep — self-contained filesuv python install / pin replaces pyenvuv export → a classic requirements.txt--exclude-newer DATE freezes the index in time