Unison file synchronizer: two-way sync between machines, from source

The problem Unison solves: two replicas, both edited

Most sync tools pick a direction. A backup utility copies from a source to a destination; a mirroring tool makes one side look like the other. Unison does neither. It stores two replicas of the same collection of files and directories on different hosts, or on different disks of one host, lets each side be modified separately, and then brings both up to date by propagating changes in each direction. Updates that do not conflict are propagated automatically; conflicting updates are detected and displayed rather than silently resolved. That distinction matters if you edit files on a laptop and on a server and neither side is authoritative. Unison is also explicit about what it is not: it is a user-level program that uses normal system calls, so there is no kernel module, no superuser requirement on either host, and no FUSE implementation. It copies data rather than mounting a remote filesystem, which means already-synchronized data stays readable and writable while offline. The audience is engineers and administrators who own both endpoints and want a deterministic, inspectable sync between them, including across operating systems, for example a Windows laptop against a Unix server.

How Unison decides what to copy

The README describes the mechanism in terms of replicas and propagation rather than a daemon architecture. Two replicas are compared, changes on each side are identified, non-conflicting changes move in both directions, and conflicts are surfaced for a human decision. Transfers of small updates to large files are optimized with a compression protocol similar to rsync, which is why the README claims it is careful with network bandwidth and runs well over slow links. Communication is typically over ssh, but direct TCP is also supported. Unison keeps private structures of its own alongside the replicas, and the README states it is careful to leave both the replicas and those private structures in a sensible state even after abnormal termination or communication failures. There is also a repeat mode driven by a filesystem monitor, so changes synchronize soon after they happen instead of waiting for the next manual run. One structural consequence of this design: the two ends must agree on the protocol, which is why version skew between hosts is a recurring operational issue rather than a detail.

Installing Unison and running a first synchronization

The project distributes Unison as source code. Many packaging systems, including GNU/Linux distributions, provide binary packages, and continuous integration builds are available for a limited set of platforms, though the README says those builds exist for testing purposes. Building instructions live in INSTALL.md. The top-level Makefile is portable across GNU Make, BSD make, Solaris make and NMAKE, and it deliberately disables parallel execution for itself because it recurses into sub-makes. The default target builds the source tree and the manpage. After building, the install target runs a helper script rather than copying files directly.

make
make install
make test

The test target runs the built binary with the text UI and the selftest flag; the Makefile warns that the binary is not built automatically for that target.

Where Unison is the wrong tool

Unison assumes you control both replicas and can run the program on both. If you need a shared namespace that many clients mount, that is a network filesystem problem, and the README positions Unison against that class of tool on purpose: it copies data so that synchronized data remains usable offline, which is the opposite of a mounted remote filesystem. If you need one authoritative copy and a read-only history, mirroring or backup software is simpler and has fewer states to reason about. The conflict model is the sharp edge: non-conflicting updates propagate automatically, but conflicting updates are only detected and displayed, so someone has to look at them. On a schedule that runs unattended, a conflict becomes a stalled item rather than a resolved one. Version agreement is a second constraint. The README instructs users to upgrade to the latest release and says bug reports are not accepted about earlier versions, yet notes that packaging systems still commonly ship 2.51 or 2.48. Mixing a distribution package on one host with a newer build on the other is therefore a realistic way to hit trouble.

Unison compared with rsync and Syncthing

rsync is the natural point of comparison because both optimize small updates to large files with a similar compression approach. The difference is direction and state. rsync runs a transfer from a source to a destination and does not maintain a model of two independently edited replicas; Unison does, and that model is what lets it propagate changes both ways and flag conflicts. Syncthing, a continuous multi-device synchronizer, also keeps multiple replicas in step, but the operational model differs: it is built around ongoing background synchronization between devices. Unison's repeat mode with a filesystem monitor narrows that gap, but Unison remains a program you invoke between two hosts that must agree on a version, which is a different trust and upgrade story from a device mesh. If your requirement is one-way publishing, rsync is less machinery. If your requirement is many devices converging continuously, a continuous synchronizer fits better than a pairwise tool.

Maintenance, releases and the GPL-3.0 licence

The README is unusually direct about maintenance: only a very small number of people work on Unison, estimated at 2.5 people and 0.1 full-time equivalents, and this has a substantial impact on how bug reports and enhancement reports are handled. The most recent release listed is v2.54.0 from 2026-05-01, preceded by v2.53.8 in 2025-11-05 and v2.53.7 in 2024-11-05. The repository is not archived and the last push was on 2026-09-20, so the source tree sees activity even when formal releases are spaced out. The README notes the master branch has historically been quite stable, which is consistent with people running from git between releases. Upgrade cost is mostly about matching versions across the machines you synchronize and about the private structures Unison maintains; the README does not document a rollback procedure for those structures, so treat a version change as something to rehearse rather than assume. On licensing, Unison is distributed under GPL-3.0 with full source available. That is a copyleft licence, and if you redistribute a modified Unison or embed it in a distributed product, the obligations attach. This is a description of the licence identifier in the repository, not legal advice.

Editorial conclusion

Adopt Unison if you need bidirectional synchronization between two machines you control, over ssh, without kernel changes or superuser rights, and you are willing to build from source or track a distribution package. Do not adopt it if you need a hosted service, a web interface, or vendor support: the README states that only a very small number of people work on it, roughly 2.5 people and 0.1 full-time equivalents. Before committing, verify which version your distribution ships, because the README says releases 2.51 and 2.48 are still common in packaging systems while earlier versions are unmaintained and bug reports about them are not accepted.

Frequently asked questions

Official sources

1. bcpierce00/unison on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases