Docker Hot Reload Fix: CHOKIDAR_USEPOLLING

If you’ve ever mounted a local directory into a Docker container and wondered why your Vite/Webpack/Node.js hot reload just… doesn’t work — you’re not alone.

The Problem

You change a file. Nothing reloads. You restart the container. Still nothing. You spend hours debugging webpack configs, only to discover it’s a filesystem limitation.

Docker on macOS and Windows uses virtualized filesystems (VirtioFS, gRPC FUSE). Native inotify events — which tools like chokidar rely on — don’t propagate from your host machine into the container.

Affected tools:

• Vite
• Webpack
• Directus Extensions
• Next.js dev mode
• Nodemon
• Any Node.js tool using chokidar

The Fix

One environment variable:

CHOKIDAR_USEPOLLING=true

Add it to your .env, docker-compose.yml, or Dockerfile.

That’s it. Hot reload works.

Why This Works

Instead of waiting for filesystem events that never arrive, polling mode checks file modification times at regular intervals. It’s slightly slower, but it actually works across Docker’s virtual filesystem bridge.

Real World Example

I maintain a Directus framework where hot reload for TypeScript extensions wasn’t working on macOS. Developers were restarting containers manually after every change.

One line in the environment config fixed it for everyone:

environment:
  - CHOKIDAR_USEPOLLING=true
  - EXTENSIONS_AUTO_RELOAD=true

TL;DR

Problem: Hot reload broken in Docker on macOS/Windows
Cause: Native file events don’t cross virtual filesystems
Fix: CHOKIDAR_USEPOLLING=true

Stop restarting containers. Start shipping.

[STATUS: HOT_RELOAD_ENABLED]