Skip to main content
Toolsbase Logo

uv Commands

Complete reference for uv, the fast Python package manager. Covers project management, Python version control, pip-compatible interface, configuration, and practical workflows with searchable cards and one-click copy.

How to UseExpand how to use
  1. 1

    Filter by category

    Switch between Project, Python & Tools, pip-Compatible, Config, and Workflow to focus on the commands you need.

  2. 2

    Search details

    Use keyword search to match command names, option notes, and example commands at once.

  3. 3

    Copy and run

    Copy the command snippet with one click, then run it directly in your terminal.

uv run

Run a command or script within the project's virtual environment.

Key points

  • --with <pkg>: Temporarily add a package for this run.
  • --python <ver>: Run with a specific Python version.

Examples

uv run python app.py
Run a script in the project's virtual environment.
uv run --with requests python fetch.py
Temporarily add requests and run the script.

uv init

Create a new Python project.

Key points

  • --name <name>: Set the project name.
  • --python <ver>: Specify the Python version to use.

Examples

uv init my-project
Create a new project in the my-project directory.
uv init --python 3.12
Initialize a project with Python 3.12.

uv add

Add dependencies to the project.

Key points

  • --dev: Add as a development dependency.
  • --optional <group>: Add to an optional dependency group.

Examples

uv add flask
Add Flask as a dependency.
uv add --dev pytest ruff
Add pytest and ruff as dev dependencies.

uv remove

Remove dependencies from the project.

Key points

  • --dev: Remove from development dependencies.
  • --optional <group>: Remove from an optional dependency group.

Examples

uv remove flask
Remove Flask from dependencies.
uv remove --dev pytest
Remove pytest from dev dependencies.

uv sync

Synchronize the project's environment with the lockfile.

Key points

  • --frozen: Sync without updating the lockfile.
  • --no-dev: Exclude development dependencies.

Examples

uv sync
Sync the environment with the lockfile.
uv sync --frozen --no-dev
CI-friendly: sync production deps only with frozen lock.

uv lock

Update the project's lockfile (uv.lock).

Key points

  • --upgrade: Upgrade all packages to latest versions.
  • --upgrade-package <pkg>: Upgrade a specific package only.

Examples

uv lock
Regenerate the lockfile.
uv lock --upgrade-package flask
Upgrade only Flask in the lockfile.

uv export

Export the lockfile to an alternate format.

Key points

  • --format requirements-txt: Export as requirements.txt.
  • --no-dev: Exclude development dependencies.

Examples

uv export --format requirements-txt > requirements.txt
Export as requirements.txt.
uv export --format requirements-txt --no-dev
Export production deps only.

uv tree

Display the project's dependency tree.

Key points

  • --depth <n>: Limit tree depth.
  • --invert: Show reverse dependencies.

Examples

uv tree
Display the dependency tree.
uv tree --depth 1
Show direct dependencies only.

uv version

Read or update the project's version.

Key points

  • --bump <type>: Bump major/minor/patch version.
  • --output-format json: Output as JSON.

Examples

uv version
Display the current version.
uv version --bump minor
Bump the minor version.

uv venv

Create a virtual environment.

Key points

  • --python <ver>: Specify the Python version.
  • --seed: Pre-install pip, setuptools, and wheel.

Examples

uv venv
Create a virtual environment in .venv.
uv venv --python 3.12 .venv312
Create with Python 3.12 in a custom directory.

uv build

Build Python packages into sdist and wheel distributions.

Key points

  • --sdist: Build source distribution only.
  • --wheel: Build wheel only.

Examples

uv build
Build both sdist and wheel.
uv build --wheel
Build wheel only.

uv publish

Upload built distributions to a package index.

Key points

  • --token <token>: Specify the PyPI API token.
  • --publish-url <url>: Set a custom repository URL.

Examples

uv publish
Upload distributions from dist/ to PyPI.
uv publish --publish-url https://test.pypi.org/legacy/
Upload to TestPyPI.

uv format

Format Python code in the project.

Key points

  • --check: Check if formatting changes are needed.
  • --diff: Show formatting diff.

Examples

uv format
Format all Python files in the project.
uv format --check
Check for formatting violations.

uv python install

Install Python versions managed by uv.

Key points

  • uv python install 3.12: Install a specific version.
  • uv python install 3.11 3.12: Install multiple versions.

Examples

uv python install 3.12
Install Python 3.12.
uv python install 3.11 3.12 3.13
Install three versions at once.

uv python list

List available Python versions.

Key points

  • --all-versions: Show all minor versions.
  • --only-installed: Show installed versions only.

Examples

uv python list
List available Python versions.
uv python list --only-installed
Show only installed versions.

uv python find

Find a Python interpreter matching the given criteria.

Key points

  • uv python find 3.12: Find a 3.12 interpreter.
  • uv python find cpython: Find a CPython interpreter.

Examples

uv python find 3.12
Show the path to Python 3.12.
uv python find
Show the default Python interpreter path.

uv python pin

Pin the project to a specific Python version.

Key points

  • Records the version in .python-version.
  • --resolved: Pin with the full version string.

Examples

uv python pin 3.12
Pin to Python 3.12 (writes .python-version).
uv python pin 3.12 --resolved
Pin with the fully resolved version string.

uv python uninstall

Uninstall a managed Python version.

Key points

  • uv python uninstall 3.11: Remove a specific version.
  • --all: Remove all managed Python versions.

Examples

uv python uninstall 3.11
Uninstall Python 3.11.
uv python uninstall --all
Remove all uv-managed Python versions.

uv python upgrade

Upgrade installed Python versions to the latest patch.

Key points

  • uv python upgrade 3.12: Upgrade 3.12 to latest patch.
  • Updates within the same minor version (3.12.x → 3.12.y).

Examples

uv python upgrade 3.12
Upgrade Python 3.12 to the latest patch.
uv python upgrade
Upgrade all installed Python versions.

uv python dir

Show the directory where uv stores Python installations.

Key points

  • Outputs the path to managed Python binaries.
  • Configurable via the UV_PYTHON_DIR environment variable.

Examples

uv python dir
Show the Python installation directory.
ls $(uv python dir)
List installed Python versions.

uv tool run

Run a command provided by a Python package without installing. uvx is an alias for this command.

Key points

  • uvx <command>: Shortcut for uv tool run.
  • --from <pkg>: Specify the providing package explicitly.

Examples

uvx ruff check .
Run ruff linter without installing.
uvx --from black black --check .
Run black formatter check.

uv tool install

Install a Python package as a global CLI tool.

Key points

  • Installs in an isolated environment per tool.
  • --python <ver>: Specify the Python version for the tool.

Examples

uv tool install ruff
Install ruff as a global tool.
uv tool install 'httpie>=3.0'
Install httpie with version constraints.

uv tool upgrade

Upgrade an installed tool to the latest version.

Key points

  • uv tool upgrade <tool>: Upgrade a specific tool.
  • --all: Upgrade all installed tools.

Examples

uv tool upgrade ruff
Upgrade ruff to the latest version.
uv tool upgrade --all
Upgrade all installed tools at once.

uv tool list

List installed global tools.

Key points

  • Shows tool name, version, and provided commands.
  • --show-paths: Include installation paths.

Examples

uv tool list
List all installed tools.
uv tool list --show-paths
List tools with their installation paths.

uv tool uninstall

Remove an installed global tool.

Key points

  • uv tool uninstall <tool>: Remove a specific tool.
  • --all: Remove all installed tools.

Examples

uv tool uninstall ruff
Uninstall ruff.
uv tool uninstall --all
Remove all installed tools.

uv tool dir

Show the directory where tools are installed.

Key points

  • Outputs the path to tool environments and binaries.
  • --bin: Show the binary link directory.

Examples

uv tool dir
Show the tool installation directory.
uv tool dir --bin
Show the tool binary PATH directory.

uv tool update-shell

Add the tool binary directory to shell PATH.

Key points

  • Automatically updates bash/zsh/fish configuration.
  • Recommended after uv tool install.

Examples

uv tool update-shell
Add the tool directory to shell PATH.
uv tool install ruff && uv tool update-shell
Install a tool and update PATH.

uv pip install

Install packages using the pip-compatible interface.

Key points

  • -r requirements.txt: Install from a requirements file.
  • --system: Install into the system Python.

Examples

uv pip install flask
Install Flask (10-100x faster than pip).
uv pip install -r requirements.txt
Install from a requirements file.

uv pip uninstall

Uninstall packages using the pip-compatible interface.

Key points

  • uv pip uninstall <pkg>: Remove a specific package.
  • -r requirements.txt: Remove packages listed in a file.

Examples

uv pip uninstall flask
Uninstall Flask.
uv pip uninstall flask sqlalchemy
Uninstall multiple packages.

uv pip compile

Compile requirements into a locked requirements.txt.

Key points

  • -o requirements.txt: Specify the output file.
  • --upgrade: Upgrade all packages and recompile.

Examples

uv pip compile requirements.in -o requirements.txt
Compile a locked requirements file.
uv pip compile pyproject.toml -o requirements.txt
Compile from pyproject.toml.

uv pip sync

Synchronize the environment with a locked requirements file.

Key points

  • Automatically removes packages not in the file.
  • Accepts multiple requirements files.

Examples

uv pip sync requirements.txt
Sync environment to match requirements.txt exactly.
uv pip sync requirements.txt dev-requirements.txt
Sync with production and dev dependencies.

uv pip freeze

Output installed packages in requirements format.

Key points

  • Outputs in pinned format (pkg==version).
  • Equivalent to pip freeze output.

Examples

uv pip freeze
List installed packages in requirements format.
uv pip freeze > requirements.txt
Save as requirements.txt.

uv pip list

List installed packages.

Key points

  • --format json: Output as JSON.
  • --outdated: Show only packages with available updates.

Examples

uv pip list
List installed packages in table format.
uv pip list --format json
Output the package list as JSON.

uv pip show

Show information about an installed package.

Key points

  • Displays version, dependencies, and install location.
  • Accepts multiple package names.

Examples

uv pip show flask
Show details about Flask.
uv pip show flask sqlalchemy
Show details for multiple packages.

uv pip tree

Display the dependency tree of installed packages.

Key points

  • --depth <n>: Limit tree depth.
  • --invert: Show reverse dependencies.

Examples

uv pip tree
Display the full dependency tree.
uv pip tree --depth 1
Show direct dependencies only.

uv pip check

Verify the consistency of installed packages.

Key points

  • Detects version conflicts and missing dependencies.
  • Ideal for CI pipeline quality checks.

Examples

uv pip check
Check environment consistency.
uv pip sync requirements.txt && uv pip check
Sync and verify consistency.

uv cache clean

Remove cached data.

Key points

  • uv cache clean: Remove all cached data.
  • uv cache clean <pkg>: Remove cache for a specific package.

Examples

uv cache clean
Clear all uv cache.
uv cache clean flask
Clear cache for Flask only.

uv cache prune

Remove unused cache entries.

Key points

  • Selectively removes old and unused cache entries.
  • Saves disk space while keeping useful cache.

Examples

uv cache prune
Remove unused cache entries.
uv cache prune && uv cache dir
Prune and check the cache directory.

uv cache dir

Show the path to the cache directory.

Key points

  • Configurable via the UV_CACHE_DIR environment variable.
  • Defaults to the OS standard cache directory.

Examples

uv cache dir
Show the cache directory path.
du -sh $(uv cache dir)
Check cache size.

uv self update

Update the uv executable to the latest version.

Key points

  • uv self update: Update to the latest stable release.
  • uv self update <ver>: Update to a specific version.

Examples

uv self update
Update uv to the latest version.
uv self update 0.7.0
Update uv to version 0.7.0.

uv auth login

Save authentication credentials for a package registry.

Key points

  • uv auth login <url>: Log in to the specified registry.
  • --token <token>: Provide a token directly.

Examples

uv auth login https://pypi.org
Log in to PyPI.
uv auth login https://private.registry.com --token $TOKEN
Log in to a private registry with a token.

uv auth logout

Remove saved authentication credentials.

Key points

  • uv auth logout <url>: Remove credentials for a registry.
  • Credentials are removed from the OS keychain.

Examples

uv auth logout https://pypi.org
Remove PyPI credentials.
uv auth logout https://private.registry.com
Remove private registry credentials.

uv generate-shell-completion

Generate shell completion scripts.

Key points

  • Supports bash, zsh, fish, and PowerShell.
  • Add the generated script to your shell config.

Examples

uv generate-shell-completion zsh > ~/.zfunc/_uv
Generate zsh completion script.
uv generate-shell-completion bash >> ~/.bashrc
Add bash completion to .bashrc.

uv run --with <package> <script.py>

Quickly run a script with temporary dependencies without adding them to the project.

Key points

  • --with: Use packages temporarily without adding to project.
  • Multiple --with flags for multiple packages.

Examples

uv run --with requests python fetch.py
Run with requests temporarily added.
uv run --with pandas --with matplotlib python analyze.py
Run an analysis script with pandas and matplotlib.

uv pip compile requirements.in -o requirements.txt

Migrate from pip-tools to uv using the compatible interface.

Key points

  • uv pip compile is a drop-in replacement for pip-compile.
  • Existing requirements.in files work as-is.

Examples

uv pip compile requirements.in -o requirements.txt
Replace pip-compile with uv.
uv pip sync requirements.txt
Replace pip-sync with uv.

uv sync --frozen --no-dev

Fast and reproducible dependency installation for CI/CD pipelines.

Key points

  • --frozen: Keep the lockfile unchanged for CI stability.
  • --no-dev: Production deps only for faster builds.

Examples

uv sync --frozen --no-dev
Fast CI install with production deps only.
uv sync --frozen && uv run pytest
Sync dependencies and run tests.

uv run --python 3.12 pytest

Test across multiple Python versions without tox or nox.

Key points

  • --python: Switch Python version per run.
  • Can replace tox/nox for simple multi-version testing.

Examples

uv run --python 3.11 pytest
Run tests with Python 3.11.
uv run --python 3.12 pytest && uv run --python 3.13 pytest
Run tests sequentially on 3.12 and 3.13.

uvx ruff check .

Run Python tools instantly without installation using uvx.

Key points

  • npx-like experience for Python tools.
  • Always uses the latest version automatically.

Examples

uvx ruff check .
Run ruff linter without installing.
uvx black --check .
Run black format check.

uv export --format requirements-txt > requirements.txt

Export requirements.txt for Docker image builds.

Key points

  • Generate Docker-compatible requirements from uv projects.
  • Combine with multi-stage builds for optimization.

Examples

uv export --format requirements-txt > requirements.txt
Generate requirements.txt for Docker.
uv export --format requirements-txt --no-dev > requirements.txt
Export production deps only.

About uv Commands

uv is an extremely fast Python package manager built by Astral. Written in Rust, it unifies pip, pip-tools, poetry, and pyenv into a single tool with 10-100x speed improvements. This reference organizes all uv commands by category with practical examples.

Features

  • All 49 uv commands organized by category
  • Options and practical examples for each command
  • Cross-search across commands, options, and examples
  • One-click copy for any command
  • Migration workflows from pip/poetry included

Use Cases

  • Quick reference for uv commands during development
  • Migrating from pip or poetry to uv
  • Setting up uv in CI/CD pipelines
  • Managing multiple Python versions with uv
  • Using uv with Docker environments

FAQ

What is the difference between uv and pip?

uv is a Rust-based package manager that is 10-100x faster than pip. It provides a pip-compatible interface (uv pip install, etc.) while also integrating project management (uv add/sync) and Python version management (uv python install).

Can uv replace pip, poetry, and pyenv entirely?

Yes. uv provides package installation (pip replacement), dependency locking (pip-tools/poetry replacement), Python version management (pyenv replacement), and tool execution (pipx replacement) in a single tool.

Can I use my existing requirements.txt and pyproject.toml?

Yes. uv pip install reads requirements.txt files directly. For pyproject.toml, uv supports both its own format and existing PEP 621-compliant files.

What is the difference between uvx and npx?

uvx is the Python equivalent of npx. It runs commands from Python packages without installing them globally. For example, uvx ruff check . runs ruff without installation.

What are the benefits of using uv in CI/CD?

uv's fast installation speed significantly reduces CI setup time. Use uv sync --frozen --no-dev to build reproducible production environments quickly.

Related Tools

mise Commandsasdf CommandsDocker CommandsGit Commands