Published on

How to Deploy FastAPI with Docker: A 15-Minute Guide (2026)

Deploying a FastAPI application with Docker takes about 10 to 15 minutes and ensures your code runs identically on any computer or cloud server. By creating a Docker image (a lightweight, standalone package containing your code and its dependencies), you eliminate the common "it works on my machine" problem. This guide uses Python 3.15 and the latest FastAPI standards to get your production-ready container live today.

What do you need to get started?

Before building your container, you need a few tools installed on your computer. Don't worry if these are new to you; most have simple installers that handle the heavy lifting.

  • Python 3.15: The latest version of the Python programming language.
  • Docker Desktop: A user-friendly application that allows you to build and run containers on your local machine.
  • A Text Editor: We recommend using VS Code with an AI assistant like Claude Sonnet 4 or Claude Opus 4.5 to help you debug any typos in real-time.
  • FastAPI: A modern web framework for building APIs (Application Programming Interfaces—tools that allow different software programs to talk to each other).

How do you structure a FastAPI project for Docker?

Organizing your files correctly is the most important step for a smooth deployment. Docker looks for specific files in specific places, so keeping things tidy prevents errors later on.

Create a new folder for your project and add these three files:

  1. main.py: This is where your actual application code lives.
  2. requirements.txt: A list of the Python packages your app needs to run.
  3. Dockerfile: A text document containing the instructions Docker uses to assemble your image.

In your main.py file, add this basic code to test the connection:

from fastapi import FastAPI

# Create the app instance
app = FastAPI()

# Define a "route" (a specific URL path people can visit)
@app.get("/")
def read_root():
    # This returns a JSON response to the browser
    return {"status": "success", "message": "Dockerized FastAPI is running!"}

Next, open requirements.txt and add the following lines to ensure you are using the latest 2026 versions:

# The core framework
fastapi>=0.130.0
# The server that runs the code
uvicorn>=0.34.0

What goes inside a Dockerfile?

The Dockerfile is like a recipe. It tells Docker which "ingredients" (software) to download and what steps to take to prepare your "meal" (the running app).

Create a file named Dockerfile (with no file extension) and paste this code:

# Step 1: Start with an official Python 3.14 or 3.15 image
FROM python:3.15-slim

# Step 2: Set the working directory inside the container
WORKDIR /code

# Step 3: Copy the requirements file into the container
COPY ./requirements.txt /code/requirements.txt

# Step 4: Install the Python dependencies
# --no-cache-dir keeps the image size small
RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt

# Step 5: Copy the rest of your app code into the container
COPY . /code

# Step 6: Tell Docker to run the app using Uvicorn
# 0.0.0.0 makes the app accessible from outside the container
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]

Why use a .dockerignore file?

A .dockerignore file tells Docker which files to skip when building your image. It works exactly like a .gitignore file if you have used Git before.

Without this file, Docker might copy bulky, unnecessary folders like __pycache__ (temporary Python files) or your local virtual environment. This makes your image larger and slower to upload.

It is normal to forget this step, but including it is a professional habit that saves time. Create a file named .dockerignore and add these lines:

__pycache__
.env
.git
venv
.vscode

How do you build and run your container?

Now that your files are ready, you will use the terminal (Command Prompt or PowerShell) to turn your code into a running container. Make sure you are inside your project folder before running these commands.

Step 1: Build the image Run this command to create your Docker image. The -t flag gives your image a "tag" or name so you can find it easily.

docker build -t my-fastapi-app .

What you should see: Docker will download the Python image and run each step in your Dockerfile. You will see "Successfully tagged my-fastapi-app:latest" at the end.

Step 2: Run the container Now, start the container using the image you just built. The -p flag connects your computer's port to the container's port.

docker run -d --name fastapi-container -p 8080:80 my-fastapi-app

What you should see: A long string of numbers and letters (the Container ID). This means your app is running in the background.

Step 3: Test the app Open your web browser and go to http://localhost:8080. You should see the JSON message: {"status": "success", "message": "Dockerized FastAPI is running!"}.

How do you troubleshoot common Docker errors?

If things don't work on the first try, don't worry. Even experienced developers run into container issues.

One common mistake is a port conflict. If you get an error saying "Port 8080 is already in use," it means another program is using that spot. You can fix this by changing the first number in the run command to something else, like 9000:80.

Another frequent issue is forgetting to save your files before building. If you change your Python code, you must run the docker build command again to update the image.

In our experience, checking the container logs is the fastest way to find a bug. You can see exactly what the Python code is complaining about by typing docker logs fastapi-container in your terminal. This will show you the same error messages you would see if you were running the app normally.

Next Steps

Congratulations on successfully containerizing your first API! This is a major milestone in becoming a modern developer.

Now that your app is in a container, you can easily move it to cloud providers like AWS, Google Cloud, or Azure. You might also want to explore Docker Compose, which helps you run multiple containers at once, such as a FastAPI app and a database.

For detailed guides, visit the official FastAPI documentation.

Read the Deploy Documentation