Python with uv

Every Python exercise and answer project uses uv. It installs Python, creates the virtual environment, resolves dependencies and runs your code, so you never touch pip or venv yourself. Answer projects ship a pyproject.toml, and uv run gives you the same environment every time.

Before you start

• Works on macOS, Linux and Windows. You don't need Python installed already, because uv downloads it.
• Allow about 100 MB for uv and each Python version it installs.

1. Install uv

macOS and Linux

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

Windows

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

Open a new terminal and check with uv --version. Homebrew works too (brew install uv), but then update it with brew upgrade uv instead of uv self update.

2. Install Python 3.12 or newer

Exercises assume Python 3.12+. Install a version, and optionally make it the default python on your machine:

uv python install 3.12
uv python install --default
uv python list

You can skip this step: uv downloads a suitable Python the first time a project needs one.

3. Create a project

uv init hello-world --python 3.12
cd hello-world

--python 3.12 sets requires-python = ">=3.12" and writes .python-version. The current uv release creates this layout:

hello-world/
├── .gitignore
├── .python-version
├── README.md
├── pyproject.toml
└── src/
    └── hello_world/
        └── __init__.py

The code lives in a package under src/, and pyproject.toml defines a hello-world command for it. Older uv versions create a flat main.py instead. Run uv self update to get the current behaviour.

4. Add packages and run code

uv add httpx
uv run hello-world
uv run python -c "import httpx; print(httpx.__version__)"

• uv add records the dependency in pyproject.toml, updates uv.lock and installs it into .venv.
• uv run syncs the environment with the lockfile, then runs the command inside it. You never need to activate .venv.
• uv remove httpx takes a package out again.

To load secrets from a .env file for one run, pass it to uv run:

uv run --env-file .env python -m hello_world

Keep .env in .gitignore. The .gitignore that uv init writes covers .venv but not .env, so add it yourself:

echo ".env" >> .gitignore

5. Test with pytest

Add pytest as a development dependency. It goes in [dependency-groups], so it isn't shipped with the package:

uv add --dev pytest

Add a function and a test:

def greet(name: str) -> str:
    return f"Hello, {name}!"
 
 
def main() -> None:
    print(greet("world"))

from hello_world import greet
 
 
def test_greet():
    assert greet("Ada") == "Hello, Ada!"

Run the tests:

uv run pytest

Because the project is a package, uv installs it into .venv, and the test can import hello_world without any path tweaks.

Answer projects use this layout. To run one, cd into it and run uv run pytest. uv creates the environment from pyproject.toml and uv.lock on first use.

Check it works

From inside hello-world:

uv run pytest -q

Expected output:

.                                                                        [100%]
1 passed in 0.01s

Troubleshooting

uv: command not found after installing. Open a new terminal. The installer adds ~/.local/bin (or %USERPROFILE%\.local\bin on Windows) to your PATH through your shell profile.

ModuleNotFoundError: No module named 'hello_world' in tests. You're on an older uv that created a flat, unpackaged project. Run uv self update and create the project again, or move the code into src/hello_world/ and add a [build-system] table as in the uv projects guide.

No interpreter found for Python >=3.12. Run uv python install 3.12. If uv is set to use only system Python, unset UV_PYTHON_PREFERENCE or UV_NO_MANAGED_PYTHON.

Windows blocks the install script. Use the exact command above. The -ExecutionPolicy ByPass part allows that one script to run without changing your system policy.

Going further

• Node.js, pnpm and TypeScript for the TypeScript exercises
• OpenRouter or a local model? before running any exercise that calls a model API