Dockerizing a FastAPI Application the Right Way

Introduction

Most "Dockerize FastAPI" tutorials produce 1 GB images that rebuild from scratch every code change and run as root. This guide shows the right way: multi-stage builds, layer caching for pip, a non-root user, and a real production process manager.

For the Java counterpart, see Dockerizing a Spring Boot Application: The Right Way.

Key takeaways

• Use python:3.12-slim, not python:3.12 — saves ~700 MB.
• Always multi-stage: compile wheels in a builder image, copy only the runtime into the final image.
• Run as a non-root user — required by most Kubernetes Pod Security Standards.
• Production servers run Gunicorn with UvicornWorker, not uvicorn --reload.
• Pin everything; cache pip install on requirements.txt separately from source.

The naive Dockerfile (don't do this)

FROM python:3.12
COPY . /app
RUN pip install -r /app/requirements.txt
CMD ["uvicorn", "app.main:app", "--reload", "--host", "0.0.0.0"]

Problems: full image, no layer cache, dev server in prod, runs as root.

The right Dockerfile

```dockerfile
# ---- builder ----
FROM python:3.12-slim AS builder
ENV PIP_NO_CACHE_DIR=1 PIP_DISABLE_PIP_VERSION_CHECK=1
WORKDIR /build
RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
 && rm -rf /var/lib/apt/lists/*
COPY requirements.txt .
RUN pip wheel --wheel-dir /wheels -r requirements.txt

# ---- runtime ---- FROM python:3.12-slim AS runtime ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 RUN useradd --create-home --uid 10001 app WORKDIR /app COPY --from=builder /wheels /wheels COPY requirements.txt . RUN pip install --no-cache /wheels/* && rm -rf /wheels COPY --chown=app:app . . USER app EXPOSE 8000 HEALTHCHECK --interval=30s --timeout=3s CMD \ python -c "import urllib.request,sys; \ sys.exit(0 if urllib.request.urlopen('http://localhost:8000/healthz').status==200 else 1)" CMD ["gunicorn", "app.main:app", "-k", "uvicorn.workers.UvicornWorker", \ "-w", "4", "-b", "0.0.0.0:8000", "--access-logfile", "-"] ```

.dockerignore

__pycache__
*.pyc
.venv
.git
.pytest_cache
.mypy_cache
tests/
.env

Worker tuning

A rule of thumb: workers = (2 × CPU) + 1 for sync, workers = CPU for async with UvicornWorker. In Kubernetes prefer fewer workers per pod and more pods — the orchestrator scales better than Gunicorn does.

docker-compose for local dev

services:
  api:
    build: .
    ports: ["8000:8000"]
    environment:
      DATABASE_URL: postgresql+asyncpg://app:app@db:5432/app
    depends_on: [db]
  db:
    image: postgres:16
    environment: { POSTGRES_USER: app, POSTGRES_PASSWORD: app }
    volumes: ["pg:/var/lib/postgresql/data"]
volumes: { pg: {} }

Production best practices

• Set PYTHONUNBUFFERED=1 so logs flush immediately.
• Drop all Linux capabilities in Kubernetes: securityContext: { capabilities: { drop: [ALL] }}.
• Don't bake secrets into images — use env vars or a secret manager.
• Scan images on every CI run (trivy image my-app).

Common mistakes

• Running pip install after COPY . . — every source edit busts the cache.
• Using --reload in production — leaks file watchers and disables workers.
• Putting Alembic migrations in CMD — run them as a separate Job, not on every pod boot.

Tools used in this tutorial

The setup below uses the following tools. Versions matter less than the role each one plays, so swap freely as long as you keep the responsibilities the same.

• Python 3.12+
• FastAPI
• Uvicorn / Gunicorn
• Pydantic v2
• SQLAlchemy 2.x
• Docker
• Kubernetes

Real-world production context

In production, a Python backend like this rarely runs as a single uvicorn process on a laptop. Teams build the app into a container image, push it to a registry, and run it behind a managed load balancer with autoscaling, health checks and centralized logging. Async FastAPI services typically use multiple Uvicorn workers managed by Gunicorn, a managed Postgres for state, Redis for cache and rate-limit counters, and an object store for uploads. The reason cloud hosting becomes a hard requirement is operational: zero-downtime rollouts, log aggregation, metrics, and TLS at the edge are not optional once real users depend on the API.

Recommended tools & deployment options

Once the tutorial works on your machine, the next question is *where do I run this for real?* These are the platforms most Python backend teams reach for:

• DigitalOcean — the simplest path from a working FastAPI container to a public URL. App Platform deploys directly from a Dockerfile, managed Postgres and Redis are one click away, and pricing is predictable. A common way to deploy the setup in this tutorial is using a cloud provider like DigitalOcean when you want to ship quickly without learning a full cloud SDK.
• AWS — the default for enterprise workloads. ECS Fargate or EKS run containers without you managing servers, RDS handles Postgres, and CloudWatch covers logs and metrics.
• Docker — the packaging format every modern deploy target understands. Build once, run the same image locally, in CI and in production.
• Kubernetes (managed: EKS, DOKS, GKE) — the right choice once you have more than a handful of services, need rolling updates, autoscaling and policy-driven networking.

A VPS or managed cloud service is required to run this architecture end-to-end — uvicorn --reload is for development, not for serving traffic.

FAQ

Gunicorn or Uvicorn alone? Uvicorn alone is fine for one pod with one worker. Gunicorn adds process supervision, graceful reloads and worker recycling.

Alpine images? Skip them for Python — musl breaks many wheels and forces source builds. -slim is the right default.

Next steps & related tutorials

Keep the momentum going with the next tutorial in this learning path:

• Next: Deploy FastAPI Applications to Kubernetes
• Next: CI/CD Pipeline for FastAPI with GitHub Actions and Docker
• Next: FastAPI Microservices Architecture
• Next: Java equivalent: Dockerizing Spring Boot