Mutagen Compose - v0.14.0


Mutagen Compose v0.14 is primarily focused on updating the underlying Mutagen and Docker Compose dependencies. Some implementation changes were required to adapt to changes in Docker Compose's internal APIs, but user-visible functionality should remain mostly unchanged. The biggest gains in this release come from fanotify support and in-volume staging, both of which should drastically improve performance.


The fanotify API is Linux's primary native recursive filesystem watching API. Using it allows Mutagen to perform accelerated scanning on Linux filesystems, avoiding the need for polling and use of the (non-recursive) inotify API. This brings Mutagen Linux performance on par with macOS and Windows, which have always had native recursive filesystem watching.

Why now? The fanotify API has existed for many years, but it only recently added the granular event notifications needed to support Mutagen with version 5.1 of the Linux kernel, and the rollout of 5.1+ kernels to distros (and Docker Desktop) took additional time after that. Support for fanotify is now broad enough to justify bringing it to Mutagen.

However, because this is a big change, and because fanotify requires CAP_SYS_ADMIN and CAP_DAC_READ_SEARCH (i.e. it basically needs to run as root), the initial rollout of this feature is going to be restricted to containers (but it should be possible to support non-container Linux environments in a future release via sudo).

Since Mutagen Compose is already experimental, support for fanotify has been turned on automatically. However, if you encounter issues with it, you can turn it off with the following configuration block:

    features: standard

In the absence of the features: standard setting, Mutagen will use the "enhanced" sidecar image, which includes fanotify support. Please note that this image includes code that is SSPL-licensed.

If you do encounter issues, please report them via Slack or the issue tracker. Thank you for your willingness to test this new feature!


This release includes the following changes from v0.13.1:

  • Added support for fanotify-based filesystem watching 🚀
  • Modified default file staging to always occur within the associated volume. This was already the case for sessions targeting volume roots, but now it also applies to those targeting volume subdirectories.
  • Updated to Compose v2.4.1
  • Updated to Go 1.18


April 23, 2022, 6:22 p.m.
Register or login to:
  • 🔍View and search all Mutagen Compose releases.
  • 🛠️Create and share lists to track your tools.
  • 🚨Setup notifications for major, security, feature or patch updates.
  • 🚀Much more coming soon!
Continue with GitHub
Continue with Google