python

Adding DevContainers to a Python Project

Mark Allen

06 Aug 2025 • 2 min read

If you're already using a Dockerfile to containerize your Python project, you're 90% of the way toward a seamless development experience using DevContainers, a feature of Visual Studio Code, which lets you define a repeatable, consistent development environment using Docker. This means zero "works on my machine" headaches and faster onboarding for your team.

In this article, we’ll show you how to wrap your existing Dockerfile in a DevContainer configuration and get up and running in VS Code.

Why DevContainers?

Think of DevContainers as your local development lab in a box. With one click, VS Code spins up a Docker container and connects your editor to it—everything from linters to language servers runs inside. You're editing in VS Code, but developing inside your container.

It’s like putting your entire development environment in a lunchbox that you can take anywhere.

Prerequisites

Before you start, make sure you have the following installed:

⚠️ On macOS/Linux, make sure your user has permission to run Docker commands without sudo.

Step 1: Check Your Dockerfile

If your project already has a Dockerfile in the root, great. It might look like this:

FROM python:3.12-slim

# Install uv.
COPY --from=ghcr.io/astral-sh/uv:0.8 /uv /uvx /bin/

WORKDIR /app

# Copy dependency file(s) first for caching
COPY pyproject.toml uv.lock ./

# Install dependencies in a separate layer
RUN uv sync --frozen

COPY . .

CMD ["uv", "run", "main.py"]

No changes are needed; DevContainers can use this as-is.

Step 2: Add DevContainer Configuration

Create a new folder in the root of your project:

mkdir .devcontainer

Then add two files:

`.devcontainer/devcontainer.json`

{
  "name": "Python Dev Container",
  "build": {
    "dockerfile": "../Dockerfile",
    "context": ".."
  },
  "customizations": {
  	"vscode": {
    	"extensions": [
          "ms-python.python",
          "ms-python.debugpy",
          "ms-python.black-formatter",
          "charliermarsh.ruff",
          "ms-python.mypy-type-checker"
        ],
        "settings": {
          "terminal.integrated.shell.linux": "/bin/bash"
        }
      }
    },
  "postCreateCommand": "uv sync",
  "remoteUser": "root",
  "features": {
    "ghcr.io/devcontainers/features/git:1": {}
  }
}

This file tells VS Code how to build and run your container.

`.devcontainer/devcontainer.env` (optional)

You can put any environment variables here:

ENV=development
DEBUG=true

Step 3: Reopen in Container

Once your DevContainer files are ready:

Open the project in VS Code.
Click the gear icon in the bottom-left corner and select Command Pallete ...
Choose Reopen in Container.

VS Code will now:

Build your Docker image (using your existing Dockerfile)
Mount your source code inside the container
Install VS Code extensions inside the container
Run your postCreateCommand

When it finishes, you're inside a fully containerized Python development environment, with all your project dependencies, extensions, and config ready to go.

Step 4: Develop Like a Pro

Inside your DevContainer, you can:

Use the built-in terminal to run Python or Poetry commands
Run tests and linters inside the same environment used for CI/CD
Use breakpoints, IntelliSense, and Jupyter notebooks

Everything just works, no virtualenvs, no system Python, no conflicts.

Commit your .devcontainer folder to git. Now, any team member can:

Clone the repo
Open it in VS Code
Click "Reopen in Container"

They’ll be developing in the exact same environment. No setup required.

Wrap-Up

Adding a DevContainer to a Python project that already uses Docker takes just a few minutes, but it can drastically improve your developer experience. For teams using VS Code, it’s a no-brainer: consistent environments, portable tooling, and faster onboarding.

If you want to take it even further, you can add Docker Compose support, define volumes for local caching, or integrate pre-commit hooks and test runners directly into the container.