docker-watch-mode-2025

Docker Compose Watch Mode (2025 GA)

Docker Compose Watch enables automatic hot reload during local development by synchronizing file changes instantly without manual container restarts.

Three Watch Actions

1. sync - Hot Reload

For frameworks with hot reload (React, Next.js, Node.js, Flask). Copies changed files directly into running container.

2. rebuild - Compilation

For compiled languages (Go, Rust, Java) or dependency changes. Rebuilds image and recreates container when files change.

3. sync+restart - Config Changes

For configuration files requiring restart. Syncs files and restarts container.

Core Procedure

1. Confirm the app already starts with docker compose up before adding watch rules.
2. Prefer sync for source directories when the runtime already reloads files.
3. Use rebuild for dependency manifests, Dockerfiles, compiled artifacts, or base-image changes.
4. Use sync+restart for configuration files that are read only at process startup.
5. Add narrow ignore rules for dependency folders, build outputs, VCS folders, caches, secrets, and generated files.
6. Run docker compose up --watch and verify both fast source edits and dependency changes.

Usage

services:
  frontend:
    build: ./frontend
    develop:
      watch:
        - action: sync
          path: ./frontend/src
          target: /app/src
          ignore: [node_modules/, .git/, dist/]
        - action: rebuild
          path: ./frontend/package.json

Start with: docker compose up --watch.

Troubleshooting Checklist

• Change not detected: verify the watched path is relative to the Compose file and not excluded by ignore.
• Hot reload not firing: confirm the application inside the container has its own watcher enabled.
• Container restarts too often: split source sync from manifest rebuild rules.
• File ownership issues: prefer named volumes for dependency directories and sync only application code.
• Slow sync: narrow watched paths and exclude build outputs or large generated folders.

References

Use docker compose watch --help and Docker's Compose Watch documentation for the current action set and CLI flags. Pair this skill with compose-patterns-2025 when watch rules interact with service dependencies, profiles, networks, or volumes.

Benefits

• Better performance than broad bind mounts
• Fewer host/container file permission issues
• Intelligent syncing with rebuild capability
• Works across supported Docker Desktop and Compose platforms