← Back to DevBytes
Docker August 13, 2026 12 min read

VS Code Docker Integration: Complete Guide

Introduction to VS Code Docker Integration

Visual Studio Code has become one of the most popular code editors for modern development, and its Docker integration is a major reason why. The VS Code Docker integration, powered primarily by the official Docker extension from Microsoft, transforms how developers build, manage, and deploy containerized applications. Instead of constantly switching between your editor and the terminal to run Docker commands, you can manage your entire container lifecycle from within VS Code.

Whether you are building microservices, working with multi-container applications using Docker Compose, or simply experimenting with containerized development environments, VS Code provides a seamless workflow that combines the power of Docker with the convenience of a rich, integrated development environment.

What Is VS Code Docker Integration?

VS Code Docker integration refers to the set of tools, extensions, and features that allow developers to work with Docker directly from the VS Code editor. The centerpiece of this integration is the Docker extension (publisher: Microsoft), which provides a graphical interface for managing Docker images, containers, volumes, networks, and registries.

Beyond the Docker extension, the integration also includes:

Why VS Code Docker Integration Matters

Working with Docker traditionally means memorizing a wide range of CLI commands and constantly context-switching between your editor and terminal. VS Code Docker integration matters because it eliminates much of this friction, leading to faster, more productive development cycles.

Key Benefits

Prerequisites

Before you begin, make sure you have the following installed and configured on your machine:

To verify Docker is running, open a terminal and execute:

docker --version
docker run hello-world

If both commands succeed, you are ready to proceed.

Installing the Docker Extension

The Docker extension is the foundation of VS Code's Docker integration. To install it:

Once installed, you will see a new Docker icon in the Activity Bar on the left side of VS Code. Clicking it opens the Docker Explorer, which displays your containers, images, networks, volumes, and registries.

Exploring the Docker Explorer

The Docker Explorer is the primary interface for managing Docker resources in VS Code. It organizes resources into several categories:

Right-clicking any resource reveals a context menu with relevant actions. For example, right-clicking a container gives you options to attach a shell, view logs, inspect the container, or open it in the browser.

Creating a Dockerfile with IntelliSense

One of the most powerful features of the Docker extension is IntelliSense for Dockerfiles. When you create a file named Dockerfile in your project, VS Code automatically provides syntax highlighting, autocomplete, and validation.

Here is an example Dockerfile for a Node.js application:

# Use the official Node.js LTS image
FROM node:20-alpine

# Set the working directory
WORKDIR /app

# Copy package files and install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy the rest of the application code
COPY . .

# Expose the application port
EXPOSE 3000

# Define the command to run the application
CMD ["node", "server.js"]

As you type FROM, RUN, COPY, or any other instruction, VS Code suggests valid completions. It also warns you about common mistakes, such as using invalid instruction names or missing arguments.

Adding a .dockerignore File

To keep your images lean, always include a .dockerignore file. This prevents unnecessary files from being copied into the image:

node_modules
npm-debug.log
.git
.gitignore
.env
.vscode
Dockerfile
docker-compose.yml
coverage
dist

Building and Running Images in VS Code

To build an image from a Dockerfile in VS Code:

Alternatively, you can build from the command palette:

Once the image is built, it appears under the Images section in the Docker Explorer. To run it:

You can also run an image with custom options by selecting Run Interactive or by configuring run options in the prompt.

Working with Docker Compose

For multi-container applications, Docker Compose is the standard tool. VS Code provides full IntelliSense for docker-compose.yml files, making it easy to define services, networks, and volumes.

Here is an example docker-compose.yml for a web application with a database:

version: "3.9"

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://user:password@db:5432/mydb
    depends_on:
      - db
    volumes:
      - .:/app
      - /app/node_modules

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydb
    ports:
      - "5432:5432"
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

To start the entire stack from VS Code:

You can also use the command palette and search for Docker Compose: Up or Docker Compose: Down.

Once running, all services appear in the Docker Explorer under Containers, grouped by their Compose project name. You can view logs for individual services, attach shells, or restart specific containers.

Debugging Applications Inside Containers

One of the most valuable capabilities of VS Code Docker integration is debugging applications running inside containers. This works by attaching the VS Code debugger to a process inside a container.

Debugging a Node.js Application

First, modify your Dockerfile to start Node.js in inspect mode:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

EXPOSE 3000 9229

CMD ["node", "--inspect=0.0.0.0:9229", "server.js"]

Next, create a launch.json configuration in the .vscode folder:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Docker: Attach to Node",
      "port": 9229,
      "address": "localhost",
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/app",
      "restart": true
    }
  ]
}

Now, start your container with port 9229 mapped:

docker run -p 3000:3000 -p 9229:9229 my-node-app

Set breakpoints in your source code, then press F5 or use the Run and Debug panel to start the "Docker: Attach to Node" configuration. VS Code will attach to the Node.js process inside the container, and your breakpoints will be hit as the application runs.

Debugging Python Applications

For Python applications, you can use the debugpy package. Here is an example Dockerfile:

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 5000 5678

CMD ["python", "-m", "debugpy", "--listen", "0.0.0.0:5678", "app.py"]

And the corresponding launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Docker: Attach to Python",
      "type": "debugpy",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5678
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}",
          "remoteRoot": "/app"
        }
      ]
    }
  ]
}

Using Dev Containers for Development

While the Docker extension helps you manage Docker resources, the Dev Containers extension takes things further by letting you use a Docker container as your full development environment. This means your editor, tools, and dependencies all live inside the container.

Creating a Dev Container

To create a dev container for your project:

Here is an example devcontainer.json:

{
  "name": "Node.js Dev Container",
  "build": {
    "dockerfile": "Dockerfile"
  },
  "forwardPorts": [3000],
  "extensions": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode"
  ],
  "postCreateCommand": "npm install",
  "remoteUser": "node"
}

And the corresponding .devcontainer/Dockerfile:

FROM mcr.microsoft.com/devcontainers/javascript-node:20

RUN apt-get update && apt-get install -y git

To reopen your project in the dev container, press Ctrl+Shift+P and select Dev Containers: Reopen in Container. VS Code will build the container, install the specified extensions, run the post-create command, and connect to the container as your development environment.

Benefits of Dev Containers

Pushing Images to Registries

VS Code makes it straightforward to push images to container registries. The Docker Explorer includes a Registries section where you can connect to Docker Hub, Azure Container Registry, GitHub Container Registry, or any private registry.

Connecting to Docker Hub

Pushing an Image

Alternatively, you can tag and push manually from the terminal:

docker tag my-node-app:latest myusername/my-node-app:latest
docker push myusername/my-node-app:latest

Best Practices for VS Code Docker Integration

1. Keep Images Small

Use minimal base images like alpine or slim variants. Multi-stage builds are also highly recommended to keep the final image lean:

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
EXPOSE 3000
CMD ["node", "dist/server.js"]

2. Always Use a .dockerignore File

Prevent sensitive files and unnecessary artifacts from entering your image. Never copy .env files, node_modules, or .git directories into production images.

3. Leverage Layer Caching

Order your Dockerfile instructions from least frequently changing to most frequently changing. Copy package.json and install dependencies before copying the rest of the source code. This way, Docker can cache the dependency layer and skip reinstalling them on every code change.

4. Use Dev Containers for Consistency

Commit your .devcontainer folder to version control. This ensures every team member develops in the same environment with the same tools and extensions.

5. Tag Images Meaningfully

Avoid using only latest. Use semantic versioning or Git commit hashes for traceability:

docker build -t my-app:1.0.0 .
docker build -t my-app:$(git rev-parse --short HEAD) .

6. Scan Images for Vulnerabilities

Use tools like docker scout or third-party scanners to identify vulnerabilities in your images before pushing them to production:

docker scout cves my-node-app:latest

7. Use Docker Compose for Local Development

Even for single-container applications, Docker Compose provides a declarative way to define how your container should run. It is easier to maintain and share than long docker run commands.

8. Configure Resource Limits

In Docker Desktop, configure CPU and memory limits to prevent containers from consuming all host resources. You can also set limits in Compose files:

services:
  web:
    build: .
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M

Common Workflows

Workflow 1: Developing a New Containerized Application

Workflow 2: Onboarding a New Developer

Workflow 3: Deploying to a Registry

Troubleshooting Common Issues

Docker Daemon Not Running

If the Docker Explorer shows an error or appears empty, ensure Docker Desktop or the Docker daemon is running. On Linux, you may need to start the service:

sudo systemctl start docker

Permission Denied on Linux

If you get permission errors when running Docker commands, add your user to the docker group:

sudo usermod -aG docker $USER

Log out and log back in for the changes to take effect.

Port Already in Use

If a container fails to start because a port is already in use, either stop the conflicting process or map the container to a different host port:

docker run -p 3001:3000 my-node-app

Dev Container Fails to Build

Check the output panel for detailed error messages. Common causes include missing Dockerfile instructions, network issues during package installation, or incompatible base images. Rebuild without cache if needed:

Ctrl+Shift+P > Dev Containers: Rebuild Container Without Cache

Conclusion

VS Code Docker integration brings the full power of containerized development into a single, cohesive editor experience. From building and managing images with the Docker Explorer to debugging applications running inside containers and creating reproducible development environments with Dev Containers, the integration covers every stage of the container lifecycle. By following the practices and workflows outlined in this guide, you can streamline your development process, reduce environment-related bugs, and ensure consistency across your entire team. Whether you are working on a small side project or a large microservices architecture, mastering VS Code's Docker tooling will make you a more efficient and effective developer.

— Ad —

Google AdSense will appear here after approval

← Back to all articles