quickstart_uv.md

uv Quickstart

This quickstart is for people who already understand the basic idea and want to try uv quickly.

It shows a compact workflow for creating a new Python project, adding dependencies, running checks, and syncing the environment.

For detailed explanations, see the earlier chapters in this guide.

What this quickstart covers

This chapter shows how to:

• install uv,
• create a new Python project,
• pin a Python version,
• add development dependencies,
• add a runtime dependency,
• configure pyproject.toml,
• run tests and Ruff,
• synchronize the project environment.

1. Install uv

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"

Check the installation:

uv --version

2. Create a new project

Create a new minimal project:

mkdir example-python-project
cd example-python-project
uv init --bare --name example-python-project --python 3.12

Pin the Python version:

uv python pin 3.12

Expected result

At this point, the project should contain:

pyproject.toml
.python-version

The pyproject.toml file describes the Python project.

The .python-version file stores the Python version selected for the project.

3. Create the package structure

Create a basic src/ layout:

mkdir -p src/example_project tests
touch src/example_project/__init__.py

On Windows PowerShell:

New-Item -ItemType Directory -Force src/example_project
New-Item -ItemType Directory -Force tests
New-Item -ItemType File -Force src/example_project/__init__.py

Add a simple module:

touch src/example_project/calculator.py

On Windows PowerShell:

New-Item -ItemType File -Force src/example_project/calculator.py

Example content:

def add(left: int, right: int) -> int:
    return left + right

4. Add pytest and Ruff as development dependencies

Add pytest:

uv add --group dev pytest

Add ruff:

uv add --group dev ruff

Expected result

The project should now contain development dependencies in pyproject.toml.

You should also see or update:

uv.lock

The uv.lock file records the exact resolved dependency versions.

Do not edit uv.lock manually.

These tools are development dependencies.

They are needed while working on the project, but they are not runtime dependencies of the package.

5. Add a runtime dependency

Runtime dependencies are packages needed by the project itself.

For example:

uv add rich

This adds rich to the project dependencies.

Expected result

The runtime dependency should appear in the [project] dependencies section of pyproject.toml.

Development tools such as pytest and Ruff should stay in the development dependency group.

This separation keeps runtime dependencies and development tools easy to understand.

Use runtime dependencies only when the actual package needs them.

Do not add test or linting tools as runtime dependencies.

6. Configure pytest and Ruff

Open pyproject.toml.

A small configuration may look like this:

[project]
name = "example-python-project"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "rich>=14.0.0",
]

[dependency-groups]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.11.0",
]

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]

[tool.ruff]
line-length = 88
target-version = "py312"
src = ["src", "tests"]

[tool.ruff.lint]
select = [
    "E",
    "F",
    "I",
    "B",
    "UP",
]

The exact dependency versions may be different.

Keep the versions generated by uv.

7. Add a test

Create:

tests/test_calculator.py

Example content:

from example_project.calculator import add


def test_add_returns_sum() -> None:
    result = add(2, 3)

    assert result == 5

Expected result

The project should now contain:

src/example_project/calculator.py
tests/test_calculator.py

The source file contains the function.

The test file verifies the expected behavior.

8. Sync the environment

Run:

uv sync

Expected result

After syncing, the project should have a local virtual environment:

.venv/

The .venv/ directory is generated locally.

It should not be committed to Git.

This creates or updates the local virtual environment.

It installs the project dependencies and development dependencies needed for the current project setup.

The local virtual environment is usually stored in:

.venv/

Do not commit .venv/ to Git.

9. Run commands inside the environment

Run tests:

uv run pytest

Run Ruff linting:

uv run ruff check .

Check formatting:

uv run ruff format --check .

Format files automatically:

uv run ruff format .

Expected result

If everything is configured correctly:

• uv run pytest should pass,
• uv run ruff check . should pass,
• uv run ruff format --check . should pass.

If the formatting check fails, run:

uv run ruff format .

Then run the checks again.

10. Lock dependencies

uv updates uv.lock when dependencies change.

You can also update the lockfile explicitly with:

uv lock

Commit both:

pyproject.toml
uv.lock

The pyproject.toml file describes dependency requirements.

The uv.lock file stores the exact resolved versions.

11. Minimal local workflow

For everyday development, use:

uv sync
uv run ruff check .
uv run ruff format --check .
uv run pytest

If formatting fails:

uv run ruff format .
uv run ruff check .
uv run ruff format --check .
uv run pytest

12. What to commit

Commit:

pyproject.toml
uv.lock
.python-version
src/
tests/

Do not commit:

.venv/
__pycache__/
.pytest_cache/
.ruff_cache/

Quick command summary

mkdir example-python-project
cd example-python-project

uv init --bare --name example-python-project --python 3.12
uv python pin 3.12

mkdir -p src/example_project tests
touch src/example_project/__init__.py
touch src/example_project/calculator.py
touch tests/test_calculator.py

uv add --group dev pytest
uv add --group dev ruff
uv add rich

uv sync

uv run ruff check .
uv run ruff format --check .
uv run pytest

Rule of thumb

Use uv to make the project easy to reproduce.

Use pyproject.toml to describe the project.

Use uv.lock to record exact dependency versions.

Use uv run to execute commands inside the project environment.