Recipe

Set up a Python project with uv

Use when: you are starting a new program or lab that will use any package from PyPI, or that you want to keep

Goal: a project folder whose pyproject.toml and uv.lock let anyone rebuild exactly your environment with one command

Taught in Projects with pyproject.toml and uv

1. 1

   Run uv init with the project's name, then cd into the new folder.

   Example

   uv init booklist, then cd booklist.

   Why: it writes pyproject.toml, .python-version, a src package and .gitignore in one step, so nothing is forgotten.

2. 2

   Open pyproject.toml and confirm requires-python says the version you mean.

   Example

   requires-python = ">=3.14".

   Why: uv picks the Python from this line and .python-version, and refuses ones that don't match.

3. 3

   Add each run-time package with uv add, quoting any version range.

   Example

   uv add "rich>=14".

   Why: the requirement goes into pyproject.toml and the exact versions into uv.lock in the same step.

4. 4

   Add test and checking tools to the dev group.

   Example

   uv add --dev pytest.

   Why: people who only run the program don't install your test tools.

5. 5

   Run the program, scripts and tools with uv run.

   Example

   uv run booklist, uv run pytest.

   Why: uv syncs the environment first, so you always run against what the lockfile says.

6. 6

   Put pyproject.toml, uv.lock and .python-version under version control, and never .venv.

   Example

   .venv/ is already listed in the .gitignore that uv init wrote.

   Why: anyone can recreate .venv with uv sync; nobody can recreate a lost lockfile.