How we build, distribute, and run applications has fundamentally transformed in the era of Docker. Docker Compose, a powerful tool for managing multi-container Docker applications, has further augmented this transformation. Now, the introduction of Docker’s “watch” feature aims to streamline the development workflow even more.

With the “watch” feature enabled, Docker Compose can automatically update active services whenever you make changes and save your code. This means services update themselves in real-time as you work, making the development process even more efficient.

Utilizing the “Watch” Feature

In Docker Compose, the watch attribute establishes a set of rules for automatically updating services based on local file changes. Each rule requires both a path pattern and an action to perform when a modification is detected. There are two available actions for watch: sync and rebuild.


When the action is set to sync, Docker Compose ensures that any changes to files on your host are instantly mirrored within the corresponding service container. This is particularly useful for frameworks that support “Hot Reload” or similar features. Sync rules can often substitute bind mounts in many development use cases, providing a finer degree of control over watched files and directories.


When the action is set to rebuild, Docker Compose automatically uses BuildKit to create a new image, replacing the current service container. This behavior is identical to executing docker compose up --build <svc>. This action is ideal for compiled languages or modifications to specific files that necessitate a full image rebuild.

Configuring the “Watch” Feature

To utilize the “watch” feature, you need to include watch sections for one or more services in your compose.yml file. Once this is done, you can launch a Compose project with docker compose up --build --wait and initiate the file watch mode by running docker compose alpha watch. Docker Compose then handles updates automatically according to your watch settings as you edit your service source files.

In this configuration, the sync action monitors your host’s ./web directory. Any modifications are synchronized to the corresponding /src/web directory in your Docker container, except for changes made to the node_modules/ directory.

The rebuild action, on the other hand, monitors the package.json file. If this file is modified in any way, Docker Compose rebuilds the image and replaces the active service container.

Once you’ve set the watch configuration, start your Docker Compose project using docker compose up --build --wait, then execute docker compose alpha watch to activate the file watch mode. Docker Compose will now automatically sync or rebuild your service every time you save a change to a file in the web/ directory or the package.json file, respectively.

This minimal example targets a Node.js application with the following structure:

├── web/
│   ├── App.jsx
│   └── index.js
├── Dockerfile
├── compose.yaml
└── package.json
    build: .
    command: npm start
        - action: sync
          path: ./web
          target: /src/web
            - node_modules/
        - action: rebuild
          path: package.json

Follow the instructions at dockersamples/avatars to quickly run a small demo app, as follows:

git clone
cd avatars
docker compose up -d
docker compose alpha watch

Open http://localhost:5735 in your browser.

A Closing Note

Docker Compose’s new “watch” feature represents a promising step towards a simpler and more efficient development process. By monitoring your files and responding to changes, Docker Compose allows developers to focus more on their code and less on the administrative tasks of building and syncing their Docker services.

In addition to the provided Node.js example, this method can be applied to other languages and frameworks. For example, Python source files for a Flask project could be synced, and a change to the requirements.txt file would trigger a rebuild.

As a best practice, always ensure that your Dockerfile is optimized for quick incremental rebuilds. This can be achieved using multi-stage builds and image layer caching. Layer caching leverages the fact that if no changes are made to your Dockerfile’s layers, subsequent builds can reuse them. Multi-stage builds, on the other hand, help maintain the final Docker images lean and focused by separating the build stage from the final stage.

By automatically updating running services as developers save their work, the “watch” feature of Docker Compose certainly eases the development process. This feature, along with the ongoing enhancements Docker consistently rolls out, helps to increase the popularity and adoption of this containerization tool.

Remember, the flexibility of Docker is what makes it so robust. This is exemplified by the “watch” feature which provides a hands-off development workflow, thereby boosting productivity. Whether you’re developing a small-scale application or a large distributed system, the “watch” feature could just be the game-changer you need.

As with many tools, the best way to understand Docker Compose’s “watch” feature is to use it. So, get your Docker services up and running, set up your watches, and let Docker do the rest. Happy coding!

Vladimir Mikhalev
I’m Vladimir Mikhalev, the Docker Captain, but my friends can call me Valdemar.

Recent Posts


DevOps Community

hey 👋 If you have questions about installation or configuration, then ask me and members of our community: