Tired of VS Code’s Dev Containers ignoring your `docker-compose.yml` file? This guide provides three practical, real-world solutions to correctly configure your `devcontainer.json` and get your multi-service development environment running smoothly.

So, Your Dev Container is Ignoring Your Docker Compose File. Let’s Fix It.

I remember it clearly. We had a new hire, brilliant kid, absolutely flying through the onboarding tasks. Then he hit the dev environment setup. For a day and a half, he was stuck. His Python service kept screaming that it couldn’t connect to `postgres-db:5432`. We checked connection strings, firewall rules, Docker networking… everything. Finally, I asked to see his `devcontainer.json`. And there it was. Or rather, there it wasn’t. He had a beautiful `docker-compose.yml` with five services, but his dev container config was just pointing at a lone Dockerfile. VS Code was happily building a completely isolated container, totally oblivious to the database he desperately needed. It’s a rite of passage, a trap we’ve all fallen into. Let’s make sure you don’t lose a day and a half to it.

The “Why”: What’s Actually Happening?

The core of the problem is a simple misunderstanding of what `devcontainer.json` does. It’s a set of instructions for VS Code, not for Docker Compose directly. When you just tell it to use a `docker-compose.yml`, it has no idea which one of your services is the “development” one. Is it the `api`? The `frontend`? The `worker`? Without explicit instructions, it often defaults to the first service defined in the file, or worse, falls back to a different build method entirely.

You have to be a traffic cop and direct VS Code. You need to tell it: “Hey, see this big `docker-compose.yml` file? I want you to spin up all these services, but I want you to attach the VS Code IDE and terminal directly inside this specific service.” Once you grasp that, the solutions become obvious.

Solution 1: The Quick Fix for Simple Setups

This is the 90% solution. You have one `docker-compose.yml`, and you just want VS Code to attach to the right service within it. Let’s say you have a simple setup for a web app.

Your `docker-compose.yml` looks something like this:

version: '3.8'
services:
  backend-api:
    build:
      context: ./backend
      dockerfile: Dockerfile.dev
    volumes:
      - ./backend:/app
    ports:
      - "8000:8000"
    depends_on:
      - postgres-main

  postgres-main:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

The mistake is having a `devcontainer.json` that doesn’t specify the service. The fix is to add one line: `”service”: “backend-api”`.

Your corrected `.devcontainer/devcontainer.json` should be:

{
  "name": "My Python App Dev",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "backend-api",
  "workspaceFolder": "/app",

  // Add your extensions and settings here
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-python.vscode-pylance"
      ],
      "settings": {
        "terminal.integrated.shell.linux": "/bin/bash"
      }
    }
  },

  // Forward the port from the container to your local machine
  "forwardPorts": [8000],

  // Run a command after the container is created
  "postCreateCommand": "pip install -r requirements.txt"
}

That’s it. Now, when you “Reopen in Container,” VS Code will run `docker-compose up -d`, wait for everything to start, and then attach its server process specifically inside the running `backend-api` container. The `postgres-main` container will be running right alongside it, accessible on the Docker network at `postgres-main:5432`.

Solution 2: The “Proper” Way with Overrides

Okay, the first solution is great, but what if your `docker-compose.yml` is also used for CI or even production-like environments? You might not want your development-specific settings (like mounting your entire source code as a volume) polluting that main file. The clean, professional way to handle this is with multiple compose files.

The strategy is to have a base `docker-compose.yml` with shared services, and a `docker-compose.dev.yml` (or whatever you want to call it) with just your development container and its specific overrides.

`docker-compose.yml` (The Base):

version: '3.8'
services:
  postgres-main:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
  
  redis-cache:
    image: redis:7-alpine

volumes:
  postgres_data:

`.devcontainer/docker-compose.dev.yml` (The Dev-Specific Service):

version: '3.8'
services:
  backend-api:
    build:
      context: ..
      dockerfile: backend/Dockerfile.dev
    volumes:
      - ..:/workspace:cached
    command: sleep infinity # Keep the container running
    depends_on:
      - postgres-main
      - redis-cache

Pro Tip: Using command: sleep infinity is a classic trick. It prevents the container from exiting if it has no long-running process, giving the dev container time to attach. Your `postCreateCommand` or terminal will run your actual app.

Now, you tell `devcontainer.json` to use both files. It will merge them, with the second file overriding the first if there are conflicts.

`.devcontainer/devcontainer.json`:

{
  "name": "My App (Override)",
  "dockerComposeFile": [
    "../docker-compose.yml",
    "docker-compose.dev.yml"
  ],
  "service": "backend-api",
  "workspaceFolder": "/workspace",

  "customizations": {
    "vscode": {
      "extensions": ["ms-python.python"]
    }
  },

  "postCreateCommand": "echo 'Container is ready!'"
}

This is my preferred method. It keeps a clean separation of concerns. Your production-like compose file stays pristine, and all the messy, volume-mounting, dev-specific stuff lives neatly in its own file, right next to the dev container configuration that uses it.

Solution 3: The Monorepo Maverick (Using Profiles)

Sometimes, you’re working in a massive monorepo with a single, gigantic `docker-compose.yml` that defines services for five different teams. You can’t just split the file, and you definitely don’t want to run all 20 services just to work on your little piece.

This is where Docker Compose profiles are a lifesaver. You can tag services with profiles and then tell Compose which profiles to activate.

Your giant `docker-compose.yml` might look like this:

version: '3.8'
services:
  # Your team's services
  my-api:
    build: ./services/my-api
    profiles: ["api-dev"] # Tag with a profile
    command: sleep infinity
    volumes:
      - ./services/my-api:/app

  # Other teams' services
  frontend-app:
    build: ./services/frontend
    profiles: ["frontend-dev"]
    ports:
      - "3000:3000"

  data-processor:
    build: ./services/data-processor
    profiles: ["data-team"]
  
  # Shared services that anyone can use
  shared-db:
    image: mysql:8
    environment:
      # ... env vars

The trick is to use an environment variable in your `devcontainer.json` to tell Docker Compose which profile to enable when it starts.

Your `.devcontainer/devcontainer.json` would then use the `COMPOSE_PROFILES` variable:

{
  "name": "Monorepo - API Dev",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "my-api",
  "workspaceFolder": "/app",

  // This is the magic part!
  "containerEnv": {
    "COMPOSE_PROFILES": "api-dev"
  },

  "customizations": { /* ... */ }
}

When you launch this dev container, Compose will only start services with the `api-dev` profile, plus any services that have no profile (like our `shared-db`). The `frontend-app` and `data-processor` will be completely ignored, saving you a ton of system resources. This is a powerful pattern for keeping sanity in complex projects.

Which One Should You Choose?

Solution	Best For…	My Take
1. The Quick Fix	Simple projects, personal projects, or when you’re just starting out.	Fast and effective. Nothing wrong with it, but you’ll outgrow it.
2. The “Proper” Way	Most professional team projects. Promotes clean separation of concerns.	This is the gold standard in my book. It’s scalable, clean, and easy for new team members to understand.
3. The Monorepo Maverick	Large, complex monorepos where multiple teams share one compose file.	A lifesaver in specific, complex situations. A bit of overkill for smaller projects.

At the end of the day, dev containers are supposed to make our lives easier, not harder. Don’t let a simple configuration issue cost you a day of productivity. Pick the pattern that fits your project, be explicit in your `devcontainer.json`, and get back to writing code.

---

🤖 Frequently Asked Questions