# uv: Python Package and Project Manager uv is a high-performance Python package and project manager that provides a unified interface for installing Python versions, managing dependencies, creating virtual environments, running scripts, formatting code, building packages, and publishing to package indexes. > [!TIP] > This page is a command reference for users who already know uv. For a guide that explains what uv is, covers installation, core workflows, benchmarks, and migration from pip and Poetry, see [uv: A Complete Guide](https://pydevtools.com/handbook/explanation/uv-complete-guide/index.md). For a hands-on first project, see [Create your first Python project](https://pydevtools.com/handbook/tutorial/create-your-first-python-project/index.md). ## When to use uv Use uv when you want a single tool for managing Python versions, virtual environments, dependencies, and package publishing instead of combining [pip](https://pydevtools.com/handbook/reference/pip/index.md), [pyenv](https://pydevtools.com/handbook/reference/pyenv/index.md), [pipx](https://pydevtools.com/handbook/reference/pipx/index.md), and others. It is a strong default for new Python projects and for developers who value fast installs and reproducible lockfiles. If your project relies on non-Python scientific libraries, [conda](https://pydevtools.com/handbook/reference/conda/index.md) may be a [better fit](https://pydevtools.com/handbook/explanation/why-should-i-choose-conda/index.md); for a comparison with pip, see [What's the difference between pip and uv?](https://pydevtools.com/handbook/explanation/whats-the-difference-between-pip-and-uv/index.md). ## Why uv? Traditional Python development involves juggling multiple tools (e.g. [pip](https://pydevtools.com/handbook/reference/pip/index.md), [pip-tools](https://pydevtools.com/handbook/reference/pip-tools/index.md), [pipx](https://pydevtools.com/handbook/reference/pipx/index.md), [poetry](https://pydevtools.com/handbook/reference/poetry/index.md), [pyenv](https://pydevtools.com/handbook/reference/pyenv/index.md), [virtualenv](https://pydevtools.com/handbook/reference/virtualenv/index.md)), each with different interfaces and behaviors. uv unifies these workflows while delivering 10-100x performance improvements over existing solutions. For background on how the ecosystem ended up so fragmented, see [Why are there so many Python packaging tools?](https://pydevtools.com/handbook/explanation/why-are-there-so-many-python-packaging-tools/index.md). * Speed: 10-100x faster than traditional Python tools * Simplicity: One tool for all Python packaging needs * Standards: Full compatibility with modern Python packaging standards * Reliability: Reproducible builds with [universal lockfiles](https://pydevtools.com/handbook/explanation/what-is-a-lock-file/index.md) ## Installation ### Quick Install ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` See [How to install uv](https://pydevtools.com/handbook/how-to/how-to-install-uv/index.md) for alternative methods and troubleshooting. ## Command Categories ### Project Management Projects use [pyproject.toml](https://pydevtools.com/handbook/reference/pyproject.toml/index.md) for configuration and `uv.lock` for dependency locking. ```bash # Initialize new project uv init my-project # Add dependencies uv add requests uv add --dev pytest # development dependency # Remove a dependency uv remove requests # Read or update the project version uv version uv version 1.2.0 uv version --bump minor # Resolve and lock dependencies uv lock # Install project and dependencies uv sync # Run commands in project environment uv run python main.py uv run pytest # Display the dependency tree uv tree # Export lockfile to requirements.txt format uv export --format requirements-txt # Build distributions uv build # Publish to PyPI uv publish ``` See [How to run tests using uv](https://pydevtools.com/handbook/how-to/how-to-run-tests-using-uv/index.md) for configuring pytest with `uv run`, and [Understanding dependency groups in uv](https://pydevtools.com/handbook/explanation/understanding-dependency-groups-in-uv/index.md) for how `[dependency-groups]` interacts with `uv sync --group`. ### Script Execution Run standalone Python scripts with automatic dependency management. ```bash # Run script with inline dependencies uv run script.py # Run with additional dependencies uv run --with requests script.py # Add dependencies to script metadata uv add --script script.py requests ``` #### Inline Script Dependencies uv allows you to specify dependencies for a script in the script itself, using the `dependencies` key. Run `uv add --script script.py requests rich` to add the `requests` and `rich` dependencies to your script. ```python # /// script # dependencies = ["requests", "rich"] # requires-python = ">=3.8" # /// import requests from rich import print ``` > [!NOTE] > Inline script dependencies are a [PEP 723](https://pydevtools.com/handbook/explanation/what-is-pep-723/index.md) compliant way to specify dependencies for a script. ### Formatting uv includes a built-in code formatting command powered by [Ruff](https://pydevtools.com/handbook/reference/ruff/index.md)'s formatter: ```bash # Format all Python files in the project uv format # Check formatting without making changes uv format --check # Show what would change uv format --diff ``` Formatting configuration is read from the project's `pyproject.toml` under `[tool.ruff.format]`, the same settings [Ruff](https://pydevtools.com/handbook/reference/ruff/index.md) uses directly. ### Security Auditing `uv audit` (added in uv 0.10.12) checks the project's locked dependencies against the [OSV](https://osv.dev/) (Open Source Vulnerabilities) database and exits with a non-zero status when any are found. ```bash # Audit the project's locked dependencies uv audit # Audit a single PEP 723 script uv audit --script analysis.py # Audit a specific dependency group uv audit --only-group dev # Ignore a vulnerability by advisory ID uv audit --ignore GHSA-xxxx-xxxx-xxxx # Ignore until an upstream fix is published uv audit --ignore-until-fixed GHSA-xxxx-xxxx-xxxx ``` For a CI walkthrough and a comparison with `pip-audit`, see [How to scan Python dependencies for vulnerabilities](https://pydevtools.com/handbook/how-to/how-to-scan-python-dependencies-for-vulnerabilities/index.md). ### Tool Management Install and run Python-based CLI tools in isolated environments. ```bash # Run tool temporarily uvx ruff check . # Install tool globally uv tool install ruff # Upgrade tools uv tool upgrade ruff uv tool upgrade --all ``` ### Python Version Management Install and manage Python interpreters without relying on system packages or [pyenv](https://pydevtools.com/handbook/reference/pyenv/index.md). ```bash # List available and installed Python versions uv python list # Install a specific Python version uv python install 3.12 # Pin the project to a Python version uv python pin 3.12 # Find where a Python version is installed uv python find 3.12 ``` See [How to install Python with uv](https://pydevtools.com/handbook/how-to/how-to-install-python-with-uv/index.md) and [How to change the Python version of a uv project](https://pydevtools.com/handbook/how-to/how-to-change-the-python-version-of-a-uv-project/index.md) for more detail. To make a uv-managed interpreter available as `python` outside a uv project, see [How to add Python to your system path with uv](https://pydevtools.com/handbook/how-to/how-to-add-python-to-your-system-path-with-uv/index.md). ### pip-Compatible Interface uv provides a drop-in replacement for [pip](https://pydevtools.com/handbook/reference/pip/index.md)/[pip-tools](https://pydevtools.com/handbook/reference/pip-tools/index.md) workflows with enhanced performance. ```bash # Create virtual environment uv venv # Install packages uv pip install requests uv pip install -r requirements.txt uv pip install -e . # editable install # Generate lockfiles uv pip compile requirements.in uv pip compile --universal requirements.in # cross-platform # Sync environment with lockfile uv pip sync requirements.txt ``` ## Learn More ### Handbook guides - [Create your first Python project](https://pydevtools.com/handbook/tutorial/create-your-first-python-project/index.md) - [Setting up testing with pytest and uv](https://pydevtools.com/handbook/tutorial/setting-up-testing-with-pytest-and-uv/index.md) - [Run your first Python script with uv](https://pydevtools.com/handbook/tutorial/how-to-run-your-first-python-script/index.md) - [How to install uv](https://pydevtools.com/handbook/how-to/how-to-install-uv/index.md) - [How to migrate from requirements.txt to pyproject.toml with uv](https://pydevtools.com/handbook/how-to/migrate-requirements.txt/index.md) - [How to change the Python version of a uv project](https://pydevtools.com/handbook/how-to/how-to-change-the-python-version-of-a-uv-project/index.md) - [How to scan Python dependencies for vulnerabilities](https://pydevtools.com/handbook/how-to/how-to-scan-python-dependencies-for-vulnerabilities/index.md) - [uv: A Complete Guide](https://pydevtools.com/handbook/explanation/uv-complete-guide/index.md) - [What's the difference between pip and uv?](https://pydevtools.com/handbook/explanation/whats-the-difference-between-pip-and-uv/index.md) ### Official documentation - [uv documentation](https://docs.astral.sh/uv/) - [Project management](https://docs.astral.sh/uv/concepts/projects/) - [Python version management](https://docs.astral.sh/uv/concepts/python-versions/) - [Tool management](https://docs.astral.sh/uv/concepts/tools/) - [Example uv Package](https://github.com/python-developer-tooling-handbook/demo-uv)