Tool reference

uv-mcp exposes 51 tools. Names mirror the uv CLI, so uv pip list is uv_pip_list. Every tool that runs uv returns the same envelope (success, exit_code, command, cwd, stdout, stderr, duration_seconds, timed_out, truncated, hint), plus parsed fields where noted.

Badges reflect the MCP tool annotations clients use to decide when to ask for confirmation: read-only tools never change anything, destructive tools can delete or overwrite state or run arbitrary code, network tools may contact package indexes. In read-only mode only read-only tools are registered.

Every uv option is available. Common options are tool parameters; resolution and index options are grouped in a resolver object on the tools that resolve packages; every other option goes in extra_args, which is validated against the installed uv (unknown flags, missing values and invalid choices are rejected with suggestions). uv_help lists every option of any command, with its choices and environment variable, and says which of the three ways to pass it.

uv command coverage

Every uv command and how uv-mcp exposes it. A test compares this table with the installed uv’s --help and fails when uv gains a command that is not listed.

uv command	uv-mcp
uv add	uv_add
uv audit	uv_audit
uv auth dir	uv_info (reported in its output)
uv auth login	uv_auth_login
uv auth logout	uv_auth_logout
uv auth token	refused: returns stored secrets into the conversation
uv build	uv_build
uv cache clean	uv_cache_clean
uv cache dir	uv_info (reported in its output)
uv cache prune	uv_cache_prune
uv cache size	uv_cache_size
uv check	uv_check
uv export	uv_export
uv format	uv_format
uv help	uv_help
uv init	uv_init
uv lock	uv_lock
uv pip check	uv_pip_check
uv pip compile	uv_pip_compile
uv pip freeze	uv_pip_freeze
uv pip install	uv_pip_install
uv pip list	uv_pip_list
uv pip show	uv_pip_show
uv pip sync	uv_pip_sync
uv pip tree	uv_pip_tree
uv pip uninstall	uv_pip_uninstall
uv publish	uv_publish
uv python dir	uv_info (reported in its output)
uv python find	uv_python_find
uv python install	uv_python_install
uv python list	uv_python_list
uv python pin	uv_python_pin
uv python uninstall	uv_python_uninstall
uv python update-shell	refused: edits the user’s shell profile
uv python upgrade	uv_python_upgrade
uv remove	uv_remove
uv run	uv_run
uv self update	uv_self_update
uv self version	uv_info (reported in its output)
uv sync	uv_sync
uv tool audit	uv_tool_audit
uv tool dir	uv_info (reported in its output)
uv tool install	uv_tool_install
uv tool list	uv_tool_list
uv tool run	uv_tool_run
uv tool uninstall	uv_tool_uninstall
uv tool update-shell	refused: edits the user’s shell profile
uv tool upgrade	uv_tool_upgrade
uv tree	uv_tree
uv venv	uv_venv
uv version	uv_version
uv workspace dir	uv_workspace_dir
uv workspace list	uv_workspace_list
uv workspace metadata	uv_workspace_metadata

Core

Always available, whatever toolsets are enabled.

uv_info

read-only · idempotent

Report the uv version, workspace root, enabled toolsets, safety settings and uv’s directories.

Call this first if unsure which project the server operates on or whether uv is installed.

No parameters.

uv_help

read-only · idempotent

List every option the installed uv accepts for a command: value type, allowed choices, env var, and how to pass it with uv-mcp (a tool parameter, the resolver object, or extra_args). Use it before reaching for an uncommon uv feature.

Parameter	Type	Default	Description
command	string	“	uv command, e.g. ‘add’, ‘pip install’, ‘python’. Empty for the list of commands.
search	string		Only options whose flag or description contains this text.

uv_command

destructive · network

Run an arbitrary uv command. Use only when no dedicated uv_* tool covers what you need.

Not run through a shell. uv auth token and update-shell commands are refused. In read-only mode only inspection commands are allowed.

Parameter	Type	Default	Description
args	list[string]	required	Arguments after uv, subcommand first, e.g. [‘workspace’, ‘list’] or [‘pip’, ‘install’, ‘—dry-run’, ‘x’]. Global flags go after the subcommand.
project_path	string		Working directory (default: workspace root).
timeout_seconds	number		Timeout in seconds (default: server setting).

Diagnostics

Toolset: diagnostics. Understand and fix a project without guessing.

uv_project_info

read-only · idempotent

Read pyproject.toml and the project tree: name, version, requires-python, dependencies, groups, extras, scripts, workspace members, lockfile, .python-version and .venv. Fast; runs no commands.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).

uv_diagnose

read-only · idempotent · network

Check that uv works, the project is valid, an interpreter is available, uv.lock is current, .venv exists and matches the lockfile, and installed packages are consistent. Each finding includes a suggested fix.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).

uv_repair

writes · idempotent · network

Fix what uv_diagnose finds: install the required Python, recreate a broken .venv, refresh uv.lock and sync (reinstalling if packages are inconsistent). Never edits pyproject.toml. Re-diagnoses afterwards.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
dry_run	bool	false	Only return the planned steps without running them.

Project

Toolset: project. The uv project workflow: pyproject.toml + uv.lock + .venv.

uv_init

writes

Create a new uv project (pyproject.toml, .python-version, README, sample code) or a PEP 723 script.

Use this instead of writing pyproject.toml by hand. Follow up with uv_add to add dependencies.

Parameter	Type	Default	Description
path	string		Directory to create the project in, or the .py file for kind=‘script’. Relative to the workspace root; defaults to the workspace root itself.
name	string		Project name (defaults to the directory name).
kind	app | lib | script	app	’app’ (default), ‘lib’ (an installable library) or ‘script’ (a single PEP 723 script).
package	bool	false	For kind=‘app’: make it an installable package with a build system.
bare	bool	false	Only create pyproject.toml (no README, sample code, .python-version or git).
python	string		Python to use: version (‘3.12’), ‘pypy@3.10’ or a path.
build_backend	string		Build backend for packaged projects, e.g. ‘uv’, ‘hatch’, ‘setuptools’.
vcs	git | none		Version control to initialise (default: git).
no_workspace	bool	false	Do not add the project to an enclosing workspace.
description	string		Project description for pyproject.toml.
no_readme	bool	false
no_pin_python	bool	false	Do not write a .python-version file.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_add

writes · network

Add dependencies to pyproject.toml, update uv.lock and sync the project environment.

This is the right way to install packages for a project; prefer it over uv_pip_install. Supports git (rev/tag/branch), local paths, extras, markers, groups, private indexes (resolver.index) and PEP 723 scripts.

Parameter	Type	Default	Description
packages	list[string]		Requirement specifiers: ‘httpx’, ‘fastapi[standard]>=0.115’, ‘git+https://github.com/org/repo’, or local paths.
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
dev	bool	false	Add to the ‘dev’ dependency group.
group	string		Add to this dependency group (e.g. ‘test’, ‘lint’).
optional	string		Add to this optional-dependency extra.
editable	bool	false	Add local path dependencies as editable.
package_extras	list[string]		Extras to enable on the added package, e.g. [‘socks’] (—extra).
marker	string		Environment marker for the requirement, e.g. “sys_platform == ‘linux’”.
bounds	lower | major | minor | exact		Version constraint style written to pyproject.toml (default: lower bound).
raw	bool	false	Write the requirement exactly as given, with no added bounds.
rev	string		Git commit for a git dependency.
tag	string		Git tag for a git dependency.
branch	string		Git branch for a git dependency.
requirements	list[string]		Requirement files, relative to project_path.
constraints	list[string]		Constraint files limiting resolved versions.
workspace	bool	false	Add a local path dependency as a workspace member.
member	string		Workspace member (—package).
script	string		PEP 723 script to operate on instead of the project.
no_sync	bool	false	Update pyproject.toml/uv.lock but do not sync the environment (—no-sync).
no_install_project	bool	false	Sync dependencies but not the project itself.
upgrade_packages	list[string]		Allow upgrading only these packages (-P).
frozen	bool	false	Use uv.lock without updating it.
locked	bool	false	Fail if uv.lock is out of date.
resolver	object		Resolution and index options.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_remove

writes · network

Remove dependencies from pyproject.toml, update uv.lock and sync the environment.

Parameter	Type	Default	Description
packages	list[string]	required	Package names to remove.
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
dev	bool	false	Remove from the ‘dev’ dependency group.
group	string		Remove from this dependency group.
optional	string		Remove from this optional-dependency extra.
member	string		Workspace member (—package).
script	string		PEP 723 script to operate on instead of the project.
no_sync	bool	false	Update pyproject.toml/uv.lock but do not sync the environment (—no-sync).
frozen	bool	false	Use uv.lock without updating it.
locked	bool	false	Fail if uv.lock is out of date.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_sync

writes · idempotent · network

Make the project’s .venv match uv.lock exactly (creating the venv and lockfile if needed).

Run this after cloning a project, after editing pyproject.toml by hand, or to repair a broken environment.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
extras	list[string]		Optional-dependency extras to include (—extra).
all_extras	bool	false
groups	list[string]		Dependency groups to include (—group).
all_groups	bool	false
no_dev	bool	false	Exclude the dev group.
only_dev	bool	false
upgrade	bool	false	Upgrade all packages to the latest allowed versions.
upgrade_packages	list[string]		Allow upgrading only these packages (-P).
reinstall	bool	false	Reinstall every package (fixes corrupted installs).
inexact	bool	false	Keep packages that are not in the lockfile.
no_install_project	bool	false	Install dependencies only, not the project.
no_install_workspace	bool	false
no_editable	bool	false	Install the project and members as non-editable.
compile_bytecode	bool	false	Compile .pyc files after installing.
active	bool	false	Sync into the active virtualenv instead of .venv.
check	bool	false	Only check whether the environment is in sync; change nothing.
dry_run	bool	false
member	string		Workspace member (—package).
all_packages	bool	false	Sync every workspace member.
script	string		PEP 723 script to operate on instead of the project.
frozen	bool	false	Use uv.lock without updating it.
locked	bool	false	Fail if uv.lock is out of date.
python	string		Python to use: version (‘3.12’), ‘pypy@3.10’ or a path.
resolver	object		Resolution and index options.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_lock

writes · idempotent · network

Resolve dependencies and write uv.lock without touching the environment. Use resolver for strategies such as lowest-version testing or exclude_newer for reproducible point-in-time locks.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
upgrade	bool	false	Allow upgrading every package.
upgrade_packages	list[string]		Allow upgrading only these packages (-P).
check	bool	false	Only check whether uv.lock is up to date; write nothing.
dry_run	bool	false	Resolve and report changes without writing uv.lock.
script	string		PEP 723 script to operate on instead of the project.
python	string		Python to use: version (‘3.12’), ‘pypy@3.10’ or a path.
resolver	object		Resolution and index options.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_run

destructive · network

Run a command or script inside the project’s environment, syncing it first.

Use this to run tests, scripts, linters and Python one-liners with the project’s dependencies. The command’s exit status is returned in exit_code (non-zero is reported as success=false).

Parameter	Type	Default	Description
command	list[string]	required	Program and arguments, e.g. [‘python’, ‘main.py’], [‘pytest’, ‘-x’], [‘python’, ‘-m’, ‘mymod’] or [‘script.py’] for a PEP 723 script. Not run through a shell.
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
with_packages	list[string]		Extra packages available only for this run (—with).
with_editable	list[string]		Local paths to add as editable for this run.
with_requirements	list[string]		Requirement files to add for this run.
module	bool	false	Run command[0] as a Python module (python -m).
env	object		Extra environment variables for the command.
env_file	string		Load environment variables from this .env file.
isolated	bool	false	Run in a temporary environment, leaving .venv untouched.
no_project	bool	false	Ignore the current project (useful for standalone scripts).
no_sync	bool	false	Do not sync the environment before running.
extras	list[string]		Optional-dependency extras to include (—extra).
all_extras	bool	false
groups	list[string]		Dependency groups to include (—group).
all_groups	bool	false
no_dev	bool	false
exact	bool	false	Remove packages not in the lockfile before running.
active	bool	false	Use the active virtualenv instead of .venv.
member	string		Workspace member (—package).
frozen	bool	false	Use uv.lock without updating it.
locked	bool	false	Fail if uv.lock is out of date.
python	string		Python to use: version (‘3.12’), ‘pypy@3.10’ or a path.
resolver	object		Resolution and index options.
timeout_seconds	number		Timeout in seconds (default: server setting).
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_tree

read-only · idempotent · network

Display the project’s resolved dependency tree from uv.lock. Use invert=true to find why a package is installed.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
depth	int		Maximum display depth.
packages	list[string]		Only show the tree rooted at these packages.
invert	bool	false	Show reverse dependencies: who depends on packages.
outdated	bool	false	Annotate packages that have newer versions available.
prune	list[string]		Hide these packages and their dependencies.
universal	bool	false	Show the tree for all platforms, not just this one.
no_dedupe	bool	false
extras	list[string]		Optional-dependency extras to include (—extra).
groups	list[string]		Dependency groups to include (—group).
all_groups	bool	false
no_dev	bool	false
script	string		PEP 723 script to operate on instead of the project.
frozen	bool	false	Read uv.lock as-is (otherwise a stale lockfile is refreshed).
python	string		Python to use: version (‘3.12’), ‘pypy@3.10’ or a path.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_export

read-only · idempotent · network

Export uv.lock as requirements.txt, pylock.toml or a CycloneDX SBOM (e.g. for Docker or other tools).

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
format	requirements.txt | pylock.toml | cyclonedx1.5	requirements.txt	Output format; cyclonedx1.5 produces an SBOM.
output_file	string		Write to this file (relative to the project). Omit to return the content in stdout.
no_hashes	bool	false
no_header	bool	false
no_emit_project	bool	false	Leave the project itself out of the output.
no_emit_packages	list[string]		Leave these packages out of the output.
prune	list[string]		Drop these packages and their exclusive dependencies.
extras	list[string]		Optional-dependency extras to include (—extra).
all_extras	bool	false
groups	list[string]		Dependency groups to include (—group).
all_groups	bool	false
no_dev	bool	false
member	string		Workspace member (—package).
all_packages	bool	false	Export the whole workspace.
script	string		PEP 723 script to operate on instead of the project.
frozen	bool	false	Use uv.lock without updating it.
locked	bool	false	Fail if uv.lock is out of date.
resolver	object		Resolution and index options.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_version

writes

Read the project’s version, or set/bump it in pyproject.toml (re-locking and syncing unless told not to).

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
value	string		Set the version to exactly this value, e.g. ‘1.4.0’.
bump	list[major | minor | patch | stable | alpha | beta | rc | post | dev]		Bump components in order, e.g. [‘minor’] or [‘patch’, ‘beta’].
dry_run	bool	false	Compute the new version without writing it.
member	string		Workspace member (—package).
no_sync	bool	false	Update pyproject.toml/uv.lock but do not sync the environment (—no-sync).
frozen	bool	false	Use uv.lock without updating it.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_format

writes · idempotent · network

Format the project’s Python code with Ruff (installed on demand by uv).

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
check	bool	false	Only report files that would change; modify nothing.
diff	bool	false	Show the formatting diff instead of writing files.
ruff_args	list[string]		Arguments passed through to ruff format, e.g. file paths.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_check

writes · idempotent · network

Run uv’s project checks (static type checking with ty). Requires a recent uv; experimental in uv.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
member	string		Workspace member (—package).
all_packages	bool	false
script	string		PEP 723 script to operate on instead of the project.
extras	list[string]		Optional-dependency extras to include (—extra).
groups	list[string]		Dependency groups to include (—group).
isolated	bool	false	Check without syncing or modifying the project environment.
frozen	bool	false	Use uv.lock without updating it.
locked	bool	false	Fail if uv.lock is out of date.
python	string		Python to use: version (‘3.12’), ‘pypy@3.10’ or a path.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_audit

read-only · idempotent · network

Check the locked dependencies against known vulnerability databases (OSV). Experimental in uv.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
no_dev	bool	false
ignore	list[string]		Vulnerability IDs to ignore (e.g. ‘GHSA-xxxx’, ‘PYSEC-…’).
ignore_until_fixed	list[string]		Vulnerability IDs to ignore until a fixed version exists.
script	string		PEP 723 script to operate on instead of the project.
frozen	bool	false	Use uv.lock without updating it.
locked	bool	false	Fail if uv.lock is out of date.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_workspace_list

read-only · idempotent

List the members of the uv workspace containing project_path (a single project is its own workspace).

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
paths	bool	false	Return member paths instead of names.
scripts	bool	false	List standalone PEP 723 scripts in the workspace instead.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_workspace_dir

read-only · idempotent

Return the workspace root directory, or the directory of one member.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
member	string		Workspace member (—package).
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_workspace_metadata

read-only · idempotent · network

Machine-readable description of the workspace: members, environment, interpreter and resolved packages. Experimental in uv; the schema may change.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
script	string		PEP 723 script to operate on instead of the project.
frozen	bool	false	Use uv.lock without updating it.
locked	bool	false	Fail if uv.lock is out of date.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

Python versions

Toolset: python. Install, find and pin interpreters.

uv_python_list

read-only · idempotent · network

List Python interpreters found on this machine and versions uv can download.

Entries with a null path are downloadable but not installed.

Parameter	Type	Default	Description
request	string		Only list versions matching this request, e.g. ‘3.12’.
only_installed	bool	false	Hide versions that are only available for download.
all_versions	bool	false	Include every patch version, not just the latest per minor.
all_platforms	bool	false	Include downloads for every OS, not just this one.
all_arches	bool	false	Include downloads for every CPU architecture.
show_urls	bool	false	Include download URLs.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_python_install

writes · idempotent · network

Download and install uv-managed Python versions. With no versions, installs the version the project requires (or the latest).

Parameter	Type	Default	Description
versions	list[string]		Version requests such as ‘3.13’, ‘3.12.4’, ‘pypy@3.10’, ‘3.14t’ (free-threaded).
default	bool	false	Also install python/python3 executables on PATH for this version.
reinstall	bool	false
upgrade	bool	false	Upgrade existing installs to the latest patch release.
force	bool	false	Replace existing python executables that uv did not install.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_python_upgrade

writes · idempotent · network

Upgrade uv-managed Python installs to their latest patch release (all of them if no versions are given).

Parameter	Type	Default	Description
versions	list[string]		Version requests such as ‘3.13’, ‘3.12.4’, ‘pypy@3.10’, ‘3.14t’ (free-threaded).
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_python_uninstall

destructive · idempotent

Remove uv-managed Python installations. Virtual environments built on them will stop working.

Parameter	Type	Default	Description
versions	list[string]		Version requests such as ‘3.13’, ‘3.12.4’, ‘pypy@3.10’, ‘3.14t’ (free-threaded).
all	bool	false	Uninstall every uv-managed Python version.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_python_find

read-only · idempotent

Return the path of the interpreter uv would use (honouring .python-version, requires-python and .venv).

Parameter	Type	Default	Description
request	string		Version request, e.g. ‘3.12’. Defaults to the project’s requirement.
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
system	bool	false	Ignore virtual environments and only consider system interpreters.
script	string		Find the interpreter for this PEP 723 script.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_python_pin

writes · idempotent

Read or write .python-version, which selects the interpreter uv uses for the project.

Parameter	Type	Default	Description
version	string		Version to pin, e.g. ‘3.12’. Omit to show the current pin.
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
global_pin	bool	false	Write the user-level default pin (uv —global) instead of the project’s.
resolved	bool	false	Pin the full interpreter version/path instead of the request as typed.
remove	bool	false	Delete the .python-version pin.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

pip interface

Toolset: pip. Environment-level package management for plain virtualenvs and requirements files.

uv_pip_install

writes · network

Install packages into a virtual environment without recording them in pyproject.toml.

For uv projects use uv_add instead so the dependency is declared and locked.

Parameter	Type	Default	Description
packages	list[string]		Requirement specifiers to install.
requirements	list[string]		Requirement files (requirements.txt, pyproject.toml, pylock.toml), relative to project_path.
editable	list[string]		Local paths to install in editable mode (-e).
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
python	string		Target environment: venv path, python path or version (default: .venv in project_path or a parent).
system	bool	false	Target the system Python. Avoid unless the user asked for it.
break_system_packages	bool	false	Allow modifying an externally-managed (PEP 668) Python.
target	string		Install into this directory instead of an environment (—target).
constraints	list[string]		Constraint files (-c) limiting resolved versions.
overrides	list[string]		Override files forcing specific versions.
extras	list[string]		Extras to install from pyproject.toml inputs.
all_extras	bool	false
groups	list[string]		Dependency groups to install from pyproject.toml.
no_deps	bool	false	Install only the named packages, not their dependencies.
upgrade	bool	false
reinstall	bool	false
compile_bytecode	bool	false
python_version	string		Resolve for this Python version, e.g. ‘3.11’.
dry_run	bool	false
resolver	object		Resolution and index options.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_pip_uninstall

destructive · idempotent

Remove packages from a virtual environment (does not edit pyproject.toml; use uv_remove for projects).

Parameter	Type	Default	Description
packages	list[string]	required	Package names to uninstall.
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
python	string		Target environment: venv path, python path or version (default: .venv in project_path or a parent).
system	bool	false	Target the system Python. Avoid unless the user asked for it.
dry_run	bool	false
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_pip_list

read-only · idempotent

List the packages installed in an environment, with versions (and latest versions when outdated=true).

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
python	string		Target environment: venv path, python path or version (default: .venv in project_path or a parent).
system	bool	false	Target the system Python. Avoid unless the user asked for it.
outdated	bool	false	Only list packages with newer versions available (queries the index).
editable_only	bool	false	Only list editable installs.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_pip_show

read-only · idempotent

Show version, location, requirements and reverse dependencies of installed packages.

Parameter	Type	Default	Description
packages	list[string]	required	Installed package names.
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
python	string		Target environment: venv path, python path or version (default: .venv in project_path or a parent).
system	bool	false	Target the system Python. Avoid unless the user asked for it.
files	bool	false	Also list the files each package installed.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_pip_freeze

read-only · idempotent

Print the environment’s installed packages in requirements.txt format (in stdout).

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
python	string		Target environment: venv path, python path or version (default: .venv in project_path or a parent).
system	bool	false	Target the system Python. Avoid unless the user asked for it.
exclude_editable	bool	false
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_pip_tree

read-only · idempotent

Display the dependency tree of the packages installed in an environment.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
python	string		Target environment: venv path, python path or version (default: .venv in project_path or a parent).
system	bool	false	Target the system Python. Avoid unless the user asked for it.
packages	list[string]		Only show the tree for these packages.
depth	int
invert	bool	false	Show reverse dependencies.
outdated	bool	false
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_pip_check

read-only · idempotent

Verify that installed packages have compatible, non-missing dependencies. success=false means problems were found.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
python	string		Target environment: venv path, python path or version (default: .venv in project_path or a parent).
system	bool	false	Target the system Python. Avoid unless the user asked for it.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_pip_compile

writes · idempotent · network

Resolve loose requirements into a fully pinned requirements.txt or pylock.toml.

Parameter	Type	Default	Description
src_files	list[string]	required	Input files: requirements.in, pyproject.toml, setup.cfg… (relative to project_path).
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
output_file	string		Write the pinned result here. Omit to return it in stdout.
format	requirements.txt | pylock.toml
universal	bool	false	Produce a platform-independent resolution.
generate_hashes	bool	false
upgrade	bool	false
upgrade_packages	list[string]		Allow upgrading only these packages.
extras	list[string]		Extras to include (pyproject.toml inputs).
all_extras	bool	false
groups	list[string]		Dependency groups to include (pyproject.toml).
constraints	list[string]		Constraint files (-c) limiting resolved versions.
overrides	list[string]		Override files forcing specific versions.
no_deps	bool	false
no_header	bool	false
python_version	string		Resolve for this Python version, e.g. ‘3.11’.
resolver	object		Resolution and index options.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_pip_sync

destructive · idempotent · network

Make an environment contain exactly the listed packages, uninstalling everything else.

Parameter	Type	Default	Description
src_files	list[string]	required	Pinned requirements.txt or pylock.toml files.
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
python	string		Target environment: venv path, python path or version (default: .venv in project_path or a parent).
system	bool	false	Target the system Python. Avoid unless the user asked for it.
constraints	list[string]		Constraint files (-c) limiting resolved versions.
compile_bytecode	bool	false
dry_run	bool	false
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

Virtual environments

Toolset: venv.

uv_venv

writes · network

Create a virtual environment. For uv projects, uv_sync creates and fills .venv automatically.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
path	string		Environment directory, relative to project_path (default: .venv).
python	string		Python to use: version (‘3.12’), ‘pypy@3.10’ or a path.
seed	bool	false	Install pip (and setuptools/wheel on old Pythons) into the venv.
clear	bool	false	Replace an existing environment at this path.
prompt	string		Prompt prefix shown when the venv is activated.
allow_existing	bool	false	Reuse an existing environment instead of failing.
system_site_packages	bool	false
relocatable	bool	false
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

Tools (uvx)

Toolset: tool. Run or install Python command-line tools in isolated environments.

uv_tool_run

destructive · network

Run a Python command-line tool in a cached, ephemeral environment (what uvx does).

Ideal for one-off linters, formatters and generators without adding them to the project.

Parameter	Type	Default	Description
command	list[string]	required	Tool executable and arguments, e.g. [‘ruff’, ‘check’, ’.’] or [‘pycowsay’, ‘hi’].
from_package	string		Package providing the executable when names differ or to pin a version, e.g. ‘httpie’, ‘ruff==0.6.0’.
with_packages	list[string]		Extra packages to install alongside the tool.
project_path	string		Working directory for the tool (default: workspace root).
python	string		Python to use: version (‘3.12’), ‘pypy@3.10’ or a path.
with_requirements	list[string]		Requirement files to add to the tool environment.
with_editable	list[string]		Local paths to add as editable to the tool environment.
constraints	list[string]		Constraint files limiting resolved versions.
overrides	list[string]		Override files forcing specific versions.
isolated	bool	false	Ignore any installed version of the tool.
env	object		Extra environment variables.
resolver	object		Resolution and index options.
timeout_seconds	number		Timeout in seconds (default: server setting).
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_tool_install

writes · idempotent · network

Install a Python CLI tool into its own isolated environment and put its executables on PATH (user-wide).

Parameter	Type	Default	Description
package	string	required	Package to install, optionally with a version or URL, e.g. ‘ruff’, ‘black==24.1.0’.
with_packages	list[string]		Extra packages to include in the tool’s environment.
with_requirements	list[string]		Requirement files to add to the tool environment.
with_editable	list[string]		Local paths to add as editable to the tool environment.
with_executables_from	list[string]		Also expose executables from these extra packages.
constraints	list[string]		Constraint files limiting resolved versions.
overrides	list[string]		Override files forcing specific versions.
editable	bool	false
force	bool	false	Overwrite executables that already exist on PATH.
upgrade	bool	false
reinstall	bool	false
python	string		Python to use: version (‘3.12’), ‘pypy@3.10’ or a path.
resolver	object		Resolution and index options.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_tool_upgrade

writes · idempotent · network

Upgrade installed tools to the latest versions their constraints allow.

Parameter	Type	Default	Description
packages	list[string]		Tools to upgrade.
all	bool	false	Upgrade every installed tool.
python	string		Python to use: version (‘3.12’), ‘pypy@3.10’ or a path.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_tool_uninstall

destructive · idempotent

Remove installed tools and their executables.

Parameter	Type	Default	Description
packages	list[string]		Tools to uninstall.
all	bool	false	Uninstall every tool.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_tool_list

read-only · idempotent

List tools installed with uv tool install, their versions and executables.

Parameter	Type	Default	Description
outdated	bool	false	Only show tools with newer versions available (queries the index).
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_tool_audit

read-only · idempotent · network

Check tools installed with uv_tool_install, and their dependencies, against known vulnerabilities (OSV). Requires uv 0.13 or newer.

Parameter	Type	Default	Description
packages	list[string]		Installed tools to audit.
all	bool	false	Audit every installed tool.
ignore	list[string]		Vulnerability IDs to ignore.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

Packaging

Toolset: build. Build and publish distributions.

uv_build

writes · idempotent · network

Build the project into distributable archives. Both sdist and wheel are built unless one is selected.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
out_dir	string		Output directory, relative to project_path (default: dist/).
sdist	bool	false	Build only a source distribution.
wheel	bool	false	Build only a wheel.
member	string		Workspace member (—package).
all_packages	bool	false	Build every workspace member.
clear	bool	false	Empty the output directory first.
build_constraints	list[string]		Constraint files for build dependencies (-b).
no_build_logs	bool	false	Hide build backend output.
force_pep517	bool	false	Always build through PEP 517, even with uv_build.
python	string		Python to use: version (‘3.12’), ‘pypy@3.10’ or a path.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_publish

destructive · network

Upload built distributions to PyPI or another index. Irreversible: a version can never be re-uploaded.

Runs as a dry run unless dry_run=false is passed explicitly. Credentials are passed to uv through environment variables, never on the command line, and are redacted from output.

Parameter	Type	Default	Description
project_path	string		Project directory, absolute or relative to the workspace root (default: workspace root).
files	list[string]		Files or globs to upload (default: dist/*).
dry_run	bool	true	Validate without uploading. Defaults to true: set false only when the user asked to publish.
index	string		Name of an index from [[tool.uv.index]] to publish to.
publish_url	string		Upload endpoint, e.g. https://test.pypi.org/legacy/.
check_url	string		Index URL used to skip files that are already uploaded.
trusted_publishing	automatic | always | never
token	string		API token. Prefer trusted publishing or UV_PUBLISH_TOKEN in the server env; never echoed back.
username	string
password	string		Password (never echoed back).
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

Cache

Toolset: cache.

uv_cache_clean

destructive · idempotent

Delete cached downloads and builds. Fixes corrupted-cache errors; later installs will re-download.

Parameter	Type	Default	Description
packages	list[string]		Only remove entries for these packages (default: everything).
force	bool	false	Remove even if another uv process holds the cache lock.
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_cache_prune

writes · idempotent

Remove unused and stale cache entries to reclaim disk space without losing what is in use.

Parameter	Type	Default	Description
ci	bool	false	Also drop pre-built wheels, keeping only what is expensive to rebuild (for CI caches).
extra_args	list[string]		Any other option of this uv command, e.g. [‘—compile-bytecode’]. Checked against the installed uv; uv_help lists every option.

uv_cache_size

read-only · idempotent

Report how much disk space the uv cache uses.

No parameters.

Authentication

Toolset: auth. Credentials for private package indexes.

uv_auth_login

writes · idempotent

Save credentials for a package index in uv’s credential store so later installs can authenticate.

Parameter	Type	Default	Description
service	string	required	Index host or URL, e.g. ‘pypi.example.com’.
token	string		Access token (sent to uv over stdin, never echoed back).
username	string
password	string		Password (sent over stdin, never echoed back).

uv_auth_logout

destructive · idempotent

Delete stored credentials for a package index.

Parameter	Type	Default	Description
service	string	required	Index host or URL, e.g. ‘pypi.example.com’.
username	string

uv itself

Toolset: self.

uv_self_update

destructive · network

Update the uv executable. Only works when uv was installed with the standalone installer.

Parameter	Type	Default	Description
target_version	string		Specific uv version to install (default: latest).
dry_run	bool	false