How to Deploy FastAPI Using Docker: Step-by-Step Guide

To deploy FastAPI using Docker, create a Dockerfile that installs dependencies and runs your app with uvicorn. Then build the Docker image with docker build and run it using docker run to serve your FastAPI app inside a container.

Syntax

A typical Dockerfile for FastAPI includes these parts:

• Base image: A Python image to start from.
• Working directory: Where your app files go inside the container.
• Copy files: Copy your app code and requirements.
• Install dependencies: Use pip to install needed packages.
• Expose port: Tell Docker which port the app listens on.
• Run command: Start the FastAPI app with uvicorn.

dockerfile

FROM python:3.11-slim
WORKDIR /app
COPY ./app /app
COPY requirements.txt /app
RUN pip install --no-cache-dir -r requirements.txt
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Example

This example shows a simple FastAPI app deployed with Docker. It includes a main.py file with a basic route, a requirements.txt listing FastAPI and Uvicorn, and a Dockerfile to containerize the app.

After building the image, running the container will serve the app on port 8000 accessible at http://localhost:8000.

python

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello from FastAPI in Docker!"}

# requirements.txt
fastapi
uvicorn[standard]

# Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY ./main.py /app
COPY requirements.txt /app
RUN pip install --no-cache-dir -r requirements.txt
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

# Commands to build and run
# docker build -t fastapi-docker .
# docker run -d -p 8000:8000 fastapi-docker

Output

INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Common Pitfalls

Common mistakes when deploying FastAPI with Docker include:

• Not exposing the correct port in the Dockerfile or docker run command.
• Forgetting to copy all necessary files into the container.
• Running uvicorn with the default host 127.0.0.1, which makes the app inaccessible outside the container.
• Not installing dependencies properly, causing runtime errors.

Always use --host 0.0.0.0 with uvicorn to allow external access.

dockerfile

# Wrong CMD (app only accessible inside container)
CMD ["uvicorn", "main:app", "--host", "127.0.0.1", "--port", "8000"]

# Correct CMD (app accessible outside container)
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Quick Reference

Tips for deploying FastAPI with Docker:

• Use a lightweight Python base image like python:3.11-slim.
• Keep your Dockerfile simple and copy only needed files.
• Expose port 8000 and run uvicorn with --host 0.0.0.0.
• Build your image with docker build -t your-image-name ..
• Run your container with docker run -d -p 8000:8000 your-image-name.

Key Takeaways

Create a Dockerfile that installs dependencies and runs FastAPI with uvicorn on host 0.0.0.0.

Build your Docker image using docker build and run it with docker run exposing port 8000.

Always set uvicorn host to 0.0.0.0 to allow external access to the containerized app.

Copy all necessary files and install dependencies inside the Docker image to avoid runtime errors.

Use lightweight base images like python:3.11-slim for faster builds and smaller images.