Unison is a file-synchronization tool for OSX, Unix, and Windows. It allows two replicas of a collection of files and directories to be stored on different hosts (or different disks on the same host), modified separately, and then brought up to date by propagating the changes in each replica to the other.

Unison shares a number of features with tools such as configuration management packages (CVS, PRCS, Subversion, BitKeeper, etc.), distributed filesystems (Coda, etc.), uni-directional mirroring utilities (rsync, etc.), and other synchronizers (Intellisync, Reconcile, etc). However, there are several points where it differs:

  • Unison runs on both Windows and many flavors of Unix (Solaris, Linux, OS X, etc.) systems. Moreover, Unison works across platforms, allowing you to synchronize a Windows laptop with a Unix server, for example.

  • Unlike simple mirroring or backup utilities, Unison can deal with updates to both replicas of a distributed directory structure. Updates that do not conflict are propagated automatically. Conflicting updates are detected and displayed.

  • Unlike a distributed filesystem, Unison is a user-level program: there is no need to modify the kernel or to have superuser privileges on either host.

  • Unison works between any pair of machines connected to the internet, communicating over either a direct socket link or tunneling over an encrypted ssh connection. It is careful with network bandwidth, and runs well over slow links such as PPP connections. Transfers of small updates to large files are optimized using a compression protocol similar to rsync.

  • Unison is resilient to failure. It is careful to leave the replicas and its own private structures in a sensible state at all times, even in case of abnormal termination or communication failures.

  • Unison has a clear and precise specification.

  • Unison is free; full source code is available under the GNU Public License.


The first time Unison is run, it will take some time to fully synchronize the specified directories. It will create archive files in the .unison directory ($HOME/.unison in Unix, $USERPROFILE\.unison in Windows) to store the structure of the sync directories and make future syncs much quicker.

Unison can be run in a very basic way by evoking it as unison [options] root1 root2 where root1 and root2 are the directories to be synced. To more easily run Unison with many options and to more easily evoke Unison from within a script or as a cron job, it is convenient to create a profile to specify the roots of synchronization and other options. If we have a profile profile.prf (stored in the .unison directory), we can use this profile by running unison profile. A simple profile will look something like this:

# profile.prf
root = /home/user
root = ssh://user@
path = Documents
path = Files

This will synchronize the local directories /home/user/Documents and /home/user/Files with the corresponding remote directories on over ssh.

A more interesting Unison profile that could be used for automating backups to a remote server could look something like this:

# profile.prf
root = /home/user
root = ssh://user@
sshargs = -C -i /path/to/ssh_key

path = Documents
ignore = Path Documents/secrets
ignore = Name *.tmp
ignore = Name {.*,*}.sw[ponx]

auto = true
batch = true
confirmbigdeletes = false

backuplocation = central
backupdir = /home/user/Unison-Backups
maxbackups = 7
backup = Name {.*,*}
backupprefix = .$VERSION

This profile will sync all of /home/user/Documents to the remote server except for the /home/user/Documents/secrets subdirectory, all files with a .tmp extension, and any swap files that vim likes to create. It will also automatically sync files without asking for confirmation (auto = true) and will store backups of files that are overwritten when they are synced in /home/user/Unison-Backups.

Helpful Links

Unison Homepage
User Manual and Reference Guide
A good Unison guide by Philip Guo

history | show excerpt | excerpt history