If you're working on Python projects especially with FastAPI and want a reproducible, isolated development environment, Dev Containers are your new best friend.

In this post, I'll walk you through setting up a custom dev container for a Python FastAPI project using VS Code, Docker, and a custom Dockerfile. You'll end up with a clean environment that works identically across all machines.

Why Use Dev Containers?

If you've ever had to run pip install a million times, or troubleshoot environment differences between machines, you know the pain of "It works on my machine."

Dev containers fix that.

They let you define your entire development environment — OS, Python version, packages, tools, VS Code extensions — in code.

What We'll Build

We'll set up:

  • A Python 3.12 FastAPI environment inside a container
  • Useful tools like curl, vim, git, and net-tools
  • A .devcontainer config to run it all with one click in VS Code
{
    "name": "Python FastAPI Devcontainer",
    "build": {
        "dockerfile": "../Dockerfile.dev"
    },
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-python.vscode-pylance",
                "ms-python.black-formatter",
                "ms-python.debugpy",
                "ms-azuretools.vscode-docker"
            ],
            "settings": {}
        }
    },
    "workspaceMount": "source=${localWorkspaceFolder},target=/code,type=bind,consistency=delegated",
    "workspaceFolder": "/code",
    "runArgs": [],
    "postCreateCommand": "pip install -r requirements.txt"
}

What This Does:

  • Uses a custom Dockerfile (../Dockerfile.dev)
  • Installs common VS Code extensions for Python
  • Mounts your local project into the container
  • Runs pip install -r requirements.txt after the container starts

Step 2: Create Your Dockerfile.dev

In your project root (outside .devcontainer), create Dockerfile.dev

FROM python:3.12-slim

RUN apt-get update && apt-get install -y curl git vim net-tools build-essential

WORKDIR /code

ENV PYTHONPATH=/code/src

What This Does:

  • Uses Python 3.12 slim image
  • Installs system tools like curl, git, and build-essential
  • Sets your working directory to /code
  • Configures the PYTHONPATH so you can cleanly import from src/

Step 3: Add Your Dependencies

Create a requirements.txt in your project root. Example:

fastapi
uvicorn
requests
black
flake8

This file is used in the postCreateCommand to automatically install your dependencies when the container is ready.

Folder Structure Recap

Your project should now look like this:

my-fastapi-project/
├── .devcontainer/
│   └── devcontainer.json
├── Dockerfile.dev
├── requirements.txt
├── src/
│   └── main.py

Step 4: Reopen in Container

Open VS Code in your project folder and press:

Ctrl + Shift + P → Dev Containers: Reopen in Container

VS Code will:

  1. Build the image from your Dockerfile.dev
  2. Mount your project into /code
  3. Install Python packages
  4. Open the dev environment

💥 Just like that, you're inside a fully set up Python FastAPI dev container.

Bonus: Run FastAPI in the Container

Let's say your main.py looks like this:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello from Dev Container!"}

You can start your app by running:

uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

Then visit: 👉 http://localhost:8000

Boom. FastAPI running in a dev container. 🎯

To Test:

None

Wrapping Up

Dev containers supercharge your development workflow by giving you predictable, repeatable, and easy-to-maintain environments.

Whether you're building a FastAPI backend or a data science project, using dev containers keeps your setup clean and consistent across your team.

Give it a try — and never again say, "but it works on my machine!" .

Got questions or thoughts? Drop them in the comments or hit me up on Github