uv: installation, environments, and reproducible Python project runs

uv manages Python versions, virtual environments, dependencies, and lockfiles.
It is especially useful for learning projects: one command restores the environment,
and uv run executes the application or tests with the correct packages.

Installation

Official installer for macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Homebrew on macOS:

brew install uv

Close and reopen the terminal, then verify the installation:

uv --version

The current installation methods are listed in the
official Astral documentation.

If the uv command is missing

Restart the terminal and retry uv --version. The installer may have updated
PATH, while an already open shell still has the old value.

If it is still missing:

• macOS/Linux: run command -v uv;
• Windows PowerShell: run Get-Command uv;
• check whether the installer printed a PATH warning;
• do not run the command inside a Python prompt marked with >>>.

Do not copy the uv executable into the project. Fix the installation or PATH.

Opening an existing project

Move into the directory containing pyproject.toml and uv.lock:

cd path/to/project
uv sync --frozen

When the project has a dev group with pytest and learning tools:

uv sync --frozen --dev

The dev group is normally enabled by default, but explicit --dev makes the
intent clear. uv sync creates .venv when it does not exist.

--frozen uses the existing uv.lock without checking or updating it. --locked
instead verifies that the lockfile matches pyproject.toml. Follow the exact command
in the starter repository README.

Running commands

You do not need to activate .venv manually:

uv run python main.py
uv run fastapi dev app/main.py
uv run pytest -q
uv run ruff check .

uv run discovers the project, synchronizes its environment, and runs the command
inside it. Run it from the project directory or one of its children.

Creating a project

uv init my-project
cd my-project
uv add fastapi --extra standard
uv add --dev pytest httpx ruff

Runtime dependencies go to [project].dependencies; development tools use the
standardized dependency group:

[dependency-groups]
dev = [
    "httpx>=0.28",
    "pytest>=8",
    "ruff>=0.12",
]

.venv and uv.lock appear after uv add, uv sync, or the first uv run.

What belongs in Git

Commit:

• pyproject.toml;
• uv.lock;
• .python-version when the project pins Python;
• source code and tests.

Do not commit:

• .venv/;
• .env with secrets;
• .pytest_cache/, .ruff_cache/, and __pycache__/.

Minimal .gitignore:

.venv/
.env
__pycache__/
.pytest_cache/
.ruff_cache/

Common problems

• No pyproject.toml found — enter the extracted project directory.
• The lockfile cannot change with --frozen — keep uv.lock; use uv lock
  without --frozen only for an intentional dependency update.
• A module is missing after sync — run through uv run and confirm the dependency
  is declared in pyproject.toml.
• The editor cannot find packages — select <project>/.venv/bin/python, or
  <project>\.venv\Scripts\python.exe on Windows.
• uv.lock changed unexpectedly — inspect git diff uv.lock; do not commit it
  when the task did not require dependency changes.

Official documentation

• uv projects
• Locking and syncing