Docker Compose Watch Hot Reload: From 30s Manual Rebuilds to 2s Auto-Sync

Why I Abandoned Bind Mount + Restart

The old docker-compose.yml was standard: volumes mount ./src into the container, docker compose up runs. The problem showed up when adding new dependencies—changing requirements.txt with bind mount only syncs the file, doesn't trigger pip install. Every dependency change required manually stopping the container, building, and restarting—averaging 30 seconds.

Docker Compose v2.22's watch mode uses inotify to monitor file changes with two action types: sync copies files directly (no rebuild), rebuild triggers a full image rebuild. Code changes hit sync (0.3s), dependency changes hit rebuild (2s).

Pitfall #1: Watch Does Nothing on macOS/Windows

Spent an hour on Mac wondering why file changes weren't reflecting. The reason is straightforward: Docker Desktop runs inside a Linux VM, and inotify events don't cross the VM boundary. macOS FSEvents and Linux inotify are completely different mechanisms—Watch mode silently fails on non-Linux hosts.

Fix: add the --poll flag to use polling instead of inotify. Performance drops slightly (~1s latency vs ~0.1s), but it actually works. Don't enable poll in production; for dev it's fine.

Pitfall #2: Sync Doesn't Install Dependencies

Changed requirements.txt, watch detected the file change, ran sync action—the file synced into the container, but pip install never ran. import httpx threw ModuleNotFoundError.

Root cause: sync only copies files, doesn't execute any build steps. When requirements.txt changes, you must use the rebuild action. The config needs separate entries: src directory gets sync (fast), dependency files get rebuild (full reconstruction).

Pitfall #3: Rebuild's 2 Seconds Is Actually Fast

Expected rebuild to be slow. Reality: a standard Python project goes from rebuild trigger to container ready in 1.8 seconds. Docker's layer cache is still active—as long as the Dockerfile hasn't changed, only the pip install layer re-runs. Compared to the 20-30 seconds of manual docker compose up --build, 2 seconds is a qualitative leap.

Configuration Example

services:
  api:
    build: .
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: ./requirements.txt
          target: /app/requirements.txt

Start command: docker compose up --watch (note: --watch, not watch).

Code changes sync in 0.3 seconds, dependency changes rebuild in 2 seconds. Compared to the previous 30-second manual workflow, the development experience improvement is immediately obvious.

👉 Join MiniMax Token Plan: AI coding acceleration for businesses

👉 Join Xiaomi MiMo Platform: Leading AI model platform with cost-effective inference

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews