Docker Compose Watch for Development Workflows

Docker Compose Watch, introduced in Docker Compose 2.22, automatically syncs file changes from your host to running containers without rebuilding images. It provides three sync modes — sync, rebuild, and restart — enabling fast development feedback loops while maintaining containerized environments. This guide covers configuration and practical workflows.

Prerequisites

# Docker Compose 2.22+ required
docker compose version
# Docker Compose version v2.27.0

Basic Configuration

# docker-compose.yml
services:
  web:
    build: .
    ports:
      - "3000:3000"
    develop:
      watch:
        # Sync source files without rebuilding
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/
            - "*.test.js"

        # Rebuild on dependency changes
        - action: rebuild
          path: ./package.json

        # Restart on config changes
        - action: sync+restart
          path: ./config
          target: /app/config

Watch Actions

• sync — copies changed files to the container (like hot reload)
• rebuild — triggers a full image rebuild and container recreation
• sync+restart — copies files and restarts the container

Running Watch Mode

# Start services with watch mode
docker compose watch

# Or in the background
docker compose watch --no-up  # If containers are already running
docker compose up -d && docker compose watch

Full-Stack Example

services:
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    develop:
      watch:
        - action: sync
          path: ./frontend/src
          target: /app/src
        - action: rebuild
          path: ./frontend/package.json

  backend:
    build: ./backend
    ports:
      - "8080:8080"
    develop:
      watch:
        - action: sync
          path: ./backend/src
          target: /app/src
        - action: sync+restart
          path: ./backend/config.yaml
          target: /app/config.yaml
        - action: rebuild
          path: ./backend/go.mod

  worker:
    build: ./worker
    develop:
      watch:
        - action: sync
          path: ./worker/tasks
          target: /app/tasks
        - action: rebuild
          path: ./worker/requirements.txt

Optimizing Watch Performance

# Use .dockerignore to reduce build context
# .dockerignore
.git
node_modules
*.md
.env.local

# Ignore patterns in watch config
develop:
  watch:
    - action: sync
      path: ./src
      target: /app/src
      ignore:
        - "**/*.test.*"
        - "**/__tests__/"
        - "**/*.map"
        - ".DS_Store"

Comparison with Other Approaches

• Volume mounts — simpler but can have performance issues on macOS/Windows, not usable in production
• Compose Watch — works identically on all platforms, mirrors production build process
• Skaffold/Tilt — more features but heavier; Watch is built into Compose

Best Practices

• Use sync for source code that supports hot reloading (React, Next.js, Vite)
• Use rebuild only for dependency files (package.json, go.mod, requirements.txt) — rebuilds are slower
• Use sync+restart for configuration files that require a process restart
• Add specific ignore patterns to avoid syncing test files, build artifacts, and IDE files
• Keep your Dockerfile optimized with multi-stage builds for fast rebuilds