uv is a Python package and project manager written in Rust. It has quickly become a default choice for new Python projects because it is dramatically faster than pip and replaces several tools at once:

  • pip and pip-tools for installing and locking dependencies
  • virtualenv and venv for environments
  • pyenv for installing Python versions
  • pipx for running command-line tools

Install uv

bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Start a new project

bash
uv init my-api
cd my-api
uv add fastapi uvicorn
uv run uvicorn main:app --reload

uv add updates pyproject.toml, resolves versions, writes uv.lock and installs into a project .venv, all in one step. uv run runs commands inside that environment without activating it.

Manage Python versions

bash
uv python install 3.13
uv python pin 3.13       # writes .python-version for the project

uv downloads Python builds on demand, so a new machine only needs uv itself.

Run tools without installing them globally

bash
uvx ruff check .
uvx pytest

Migrate an existing pip project

From requirements.txt

bash
uv init --bare              # creates pyproject.toml without sample files
uv add -r requirements.txt  # imports dependencies
uv add --dev -r requirements-dev.txt
uv sync                     # creates .venv and installs everything

Commit pyproject.toml and uv.lock. Remove the old requirements files once CI is switched over, or keep generating them if other tools need them:

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

Keep using pip commands

If you are not ready to change workflows, uv has a pip-compatible interface:

bash
uv venv
uv pip install -r requirements.txt

Use uv in CI and Docker

yaml
- uses: astral-sh/setup-uv@v6
  with: { enable-cache: true }
- run: uv sync --locked
- run: uv run pytest

--locked fails if the lockfile is out of date, which keeps CI reproducible.

Things to know

  • The lockfile is cross-platform, so one uv.lock works on Windows, macOS and Linux.
  • Workspaces support monorepos with several Python packages.
  • Dependency groups (--dev, custom groups) replace separate requirements files.

Key takeaways

  • uv replaces pip, venv, pip-tools, pyenv and pipx with one fast tool.
  • uv add, uv sync and uv run cover most daily work.
  • Migrate with uv add -r requirements.txt and commit uv.lock.
  • Use uv sync --locked in CI for reproducible builds.