Lightweight Docker unison server based on alpine linux for file synchronization
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


A docker volume container using Unison for fast two-way folder sync. Created as an alternative to slow docker for mac volumes on OS X.

This image is trying to be as minimal as possible and it only weights 14.41MB.

The docker image is available on Docker Hub:



First, you can launch a volume container exposing a volume with Unison.

$ CID=$(docker run -d -p 5000:5000 -e UNISON_DIR=/data -v /data onnimonni/unison)

You can then sync a local folder to $UNISON_DIR (default value: /data) in the container with:

$ unison . socket://<docker>:5000/ -auto -batch

Next, you can launch a container connected with the volume under /data.

$ docker run -it --volumes-from $CID ubuntu /bin/sh


This container has few envs that you can alter.

UNISON_DIR - This is the directory which receives data from unison inside the container. This is also the directory which you can use in other containers with volumes_from directive.

UNISON_GID - Group ID for the user running unison inside container.

UNISON_UID - User ID for the user running unison inside container.

UNISON_USER - User name for the sync user ( UID matters more )

UNISON_GROUP - Group name for the sync user ( GID matters more )

Docker Compose

If you are using Docker Compose to manage a dev environment, use the volumes_from directive.

The following docker-compose.yml would mount the /var/www/project folder from the unison container inside your mywebserver container.

  build: .
    - unison
  image: onnimonni/unison
    - UNISON_DIR=/var/www/project
    - UNISON_UID=10000
    - UNISON_GID=10000
    - "5000:5000"
    - /var/www/project

You can then sync a local folder, using the unison client, to /var/www/project in the container with:

$ unison . socket://<docker>:5000/ -ignore 'Path .git' -auto -batch

You can use -repeat watch to sync everytime when files change:

$ unison . socket://<docker>:5000/ -repeat watch -ignore 'Path .git' -auto -batch

NOTE: In order to use -repeat option you need to install unison-fsmonitor.

Installing Unison Locally

Unison requires the version of the client (running on the host) and server (running in the container) to match.

Docker images are versioned with the version of unison which is installed in the container. You can use onnimonni/unison:2.51.2 image to use unison with 2.51.2 version.

  • 2.40.102 (available via apt-get install unison on Ubuntu 14.04, 14.10, 15.04)
  • 2.48.4 (available via apt install unison on Ubuntu 18.04)
  • 2.51.2 (available via brew install unison on Mac OS X) [default]

Additional versions can be added easily on request. Open an Issue if you need another version.

Installing unison-fsmonitor on OSX (unox)

# This is dependency for unox
$ pip install MacFSEvents

# unox is unison-fsmonitor script for Mac
$ curl -o /usr/local/bin/unison-fsmonitor -L
$ chmod +x /usr/local/bin/unison-fsmonitor


Thanks for leighmcculloch for showing me how to use unison with docker.


This docker image is licensed under GPLv3 because Unison is licensed under GPLv3 and is included in the image. See LICENSE.