fastapi-uv-starter

A starter project using Python, FastAPI and uv.

• fastapi-uv-starter
  • Description
  • Prerequisites
    • 1. Install Python 3 and uv
    • 2. Create a virtual environment with all necessary dependencies
  • Run application
    • Development mode
    • Production mode
  • Testing
    • With coverage
    • With coverage and HTML output
  • Linting
  • Formatting
  • Containerisation
    • 1. Build image and tag it as fastapi-uv-starter
    • 2. Run a container of the previously tagged image (fastapi-uv-starter)
    • 3. Check running containers
    • 4. Hit sample endpoint

Description

A project starter for personal usage containing the following:

• Python 3.13.*
• FastAPI web framework
• Structured logging using structlog
• Dependency management using uv
• Containerisation using a Dockerfile
• Testing with pytest and optionally with coverage with pytest-cov
• Linting/formatting using ruff
• .gitignore

Prerequisites

• Python 3.13.*
• uv

1. Install Python 3 and uv

MacOS (using brew)

brew install [email protected] uv

Ubuntu/Debian

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.13
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create a virtual environment with all necessary dependencies

From the root of the project execute:

uv sync

Run application

Development mode

uv run fastapi dev

Production mode

uv run fastapi run

Testing

uv run pytest

With coverage

uv run pytest --cov=app

With coverage and HTML output

uv run pytest --cov-report html --cov=app

Linting

uv run ruff check app/* tests/*

Formatting

uv run ruff format app/* tests/*

Containerisation

The following podman commands are direct replacements of the Docker CLI. You can see that their syntax is identical:

1. Build image and tag it as fastapi-uv-starter

podman image build -t fastapi-uv-starter .

2. Run a container of the previously tagged image (fastapi-uv-starter)

Run our FastAPI application and map our local port 8000 to 80 on the running container:

podman container run -d --name fastapi-uv-starter -p 8000:80 --network bridge fastapi-uv-starter

3. Check running containers

podman ps

CONTAINER ID  IMAGE                            COMMAND               CREATED         STATUS             PORTS                 NAMES
78586e5b4683  localhost/fastapi-uv-starter:latest  uvicorn main:app ...  13 minutes ago  Up 5 minutes ago  0.0.0.0:8000->80/tcp  nifty_roentgen

4. Hit sample endpoint

Our FastAPI server now runs on port 8000 on our local machine. We can test it with:

curl -i http://localhost:8000/healthcheck

Output:

HTTP/1.1 200 OK
server: uvicorn
content-length: 0