nodemon file watching: native events vs polling across operating systems

Short answer

nodemon delegates all file watching to chokidar, which uses native OS mechanisms by default: inotify on Linux, FSEvents on macOS, and ReadDirectoryChangesW on Windows. Polling is not the default on any platform. Polling is the documented fallback you opt into with the --legacy-watch (-L) flag or "legacyWatch": true in nodemon.json, and it is the standard workaround when native events cannot reach the watcher — most commonly Docker bind mounts, network filesystems (NFS/SMB), VM shared folders, and some WSL setups.

1. Can you see or control which mechanism is active?

Control is one‑directional: you can force polling (legacyWatch: true), but there is no documented option to force native mode if the environment can’t deliver native events. nodemon also does not prominently announce which mechanism is in use. The practical indicators are behavioral:

• Missed restarts after edits → native events aren’t arriving; switch to polling.
• Sustained CPU/I/O load with legacyWatch on a large tree → polling cost; tighten ignore rules.

Running nodemon with verbose output (--verbose or --debug) shows which paths and how many files are being watched; that is the most useful diagnostic it exposes.

2. Where native events are unreliable

• Docker bind mounts from macOS/Windows hosts: edits made on the host often don’t propagate inotify events into the container. Enable legacyWatch inside the container.
• NFS/SMB mounts and VirtualBox/VMware shared folders: the server/host generates the change, so the guest’s inotify never fires. Polling required.
• WSL: WSL1 had notoriously broken inotify on Windows drives (/mnt/c). WSL2 works well for files inside the Linux filesystem, but watching Windows‑mounted paths from WSL2 still has known event‑delivery gaps. Best practice: keep the project in the Linux filesystem, or use polling.

3. Verifying a restart actually fired

nodemon prints a "restarting due to changes…" line naming the changed file(s). The definitive test:

1. Start nodemon, note the watched‑file count in its startup output.
2. Edit a file from the same side your team edits from (e.g., host editor on a bind‑mounted file).
3. If no restart line appears, enable "legacyWatch": true and repeat. If it now fires, native events were the problem.

On Linux, also rule out watch‑limit exhaustion, which silently drops watches on large trees:

cat /proc/sys/fs/inotify/max_user_watches
# if too low:
sudo sysctl fs.inotify.max_user_watches=524288

EMFILE / "too many open files" errors point the same direction: narrow watch paths, add ignore patterns (nodemon honors .gitignore‑style ignores), and raise the descriptor limit.

Recommended team configuration

For a mixed‑OS team with some members in containers, a conservative nodemon.json is:

{
  "watch": ["src"],
  "ignore": ["node_modules/**", "dist/**", "*.log"],
  "ext": "js,ts,json"
}

Keep legacyWatch off by default (native events are cheaper), and enable it per‑developer via environment‑specific config or CLI flag only for those on Docker bind mounts, network mounts, or WSL‑on‑Windows paths. Combine polling with aggressive ignores, since polling cost scales with tree size.

Version caveat: chokidar and nodemon defaults, and Docker Desktop’s mount event propagation, change between releases. Confirm the installed versions and run the edit‑and‑observe test above on each environment before committing the team config.