Welcome to the Mutagen documentation!

This documentation is divided into sections that can be read independently or in order. You don’t need to read all of it to use Mutagen — much of it just covers more specific or advanced features.

For a general overview, start with the Design and usage guide below.

Getting started

For information on Mutagen’s design, installation, and usage, check out the following guides:


Mutagen supports a growing list of synchronization transports, which you can read about in the following guide:


If Mutagen’s out-of-the-box configuration doesn’t meet your needs, it offers a flexible configuration system supporting a broad range of behavioral tweaks. All of these behaviors are configured using the same hierarchical configuration mechanisms. You can read about these mechanisms in the configuration guide:

Synchronization modes

One of Mutagen’s most flexible design elements is its support for various synchronization modes with different directionalities and conflict resolution behaviors. You can read about these in the following guide:

Ignoring content

With most development workflows, there’s often a need to exclude content from synchronization. Mutagen has a flexible ignore specification system that will be familiar to most users. It also has support for ignoring certain classes of files without the need for manual specification. Learn more with the following guide:

Other behavioral settings

Mutagen’s out-of-the-box behavior is designed to be portable and developer-focused. Additional options to control specific behavior are also available and described in the following guides:

Version control systems

Mutagen is designed to be used in conjunction with, but orthogonally to, version control systems. The following guide outlines best practices for using Mutagen with these tools:


Mutagen comes with a number of best-effort safety mechanisms designed to prevent the accidental replacement or deletion of files. It’s also designed for robustness to connection dropouts and comes with controls to limit file size. A quick summary of these features is available in the following guides: