Configuring Unison on Windows

Unison is a free file sync utility that runs on Windows, OS X, or Linux. As with most of these things, Windows support is a bit of an afterthought, and can be tricky to work with. Here’s a step-by-step list of what I did to get it working. Note that I’m only setting things up for mirroring (ie one-way sync) so I only installed the SSH server and Unison text client on the “client” and the remainder of the stuff on the “server.” If you’re doing full 2-way sync, perform all the installations on both machines.

  1. Install GTK for Windows. I tried a couple of installers that didn’t work, but found an installer as part of this project that worked great.
  2. Install an SSH server. freeSSHd is a great little program, and it’s a tiny download. Make sure to install as a Windows service when it asks you.
  3. Configure the SSH server. Starting up the freeSSHd GUI actually tries to open another SSH server, even though you configured one to run as a service. This means that changes you make in the GUI won’t take effect until you restart the service. The only thing you’ll need to do is create a user, with password stored as SHA1 hash, that is allowed to use the shell.
  4. Configure environment variables. Unison expects to find an environment variable called HOME and will complain if it doesn’t find it. I set mine to C: and it’s happy with that.
  5. Get a fake SSH client. Unison expects that it can say ssh and something will answer. So first download PuTTY and Plink and make sure they’re in your path. Then download the Unison-ssh wrapper and make sure it’s in your path. It will redirect any calls for ssh.exe to plink.exe
  6. Put the Unison client in place. Windows binaries are available here. Rename the binaries something simple like unison-gui and unison. I suggest naming the text version unison as this is the name that Unison expects the client to have. Make sure the binaries are also in your path.
  7. Test your SSH. At this point you should be able to go to a command prompt and do this:
    ssh -l username -pw password server "unison -version"
    and get something like this:
    unison version 2.27.57
  8. Test your Unison. Assuming that worked, try testing Unison with the -testserver parameter:
    unison -testserver -sshargs "-l username -pw password" c: ssh://server//
    which should give you something like this:
    Connected [//server1/c:/ -> //server2/c:/]
  9. Set up your files. Congratulations, the servers are talking to each other! I suggest running the next step in the GUI, as there may be a lot of initial file syncing to be done:
    unison-gui -sshargs "-l username -pw password" c:directory ssh://server//directory
    It’s pretty self-explanatory, arrows point in the direction of updates, click “Go” when you’ve got it set up how you want it.

After the initial setup, you can continue using the GUI, or start using the text mode. There are a number of preferences that make things easier, which you can learn about in the documentation. As I mentioned, I’m using this for mirroring, so I use the -force parameter to make sure the “server” always takes priority over the “client.”

12 Replies to “Configuring Unison on Windows”

  1. Hi Mike,

    I came across your site while trying to set up Unison. I have been trying with no joy now for almost a week so any help would be greatly appreciated.

    Here is what I would like to do – hopefully you will be able to help, I have a shared Windows XP Prof. Computer at home but I do most of my work on a linux laptop. I would like to use Unison to sync between the two. I work almost excusively on the laptop so the home windows is no more than a back up.

    I have installed freeSSHd on the windows machine and have been able to ssh into it from my linux Laptop. I added the path for Unison and freeSSHd in my environment variables and set Home as C: as suggested. However I am getting the following error when trying to sync a dummy file : Environment variable HOME unbound: executing server in current directory13\

    Have you any idea how to fix this any suggestions would be great.
    By the way I am from Northern Ireland and have an Uncle living on Vancouver Island – I must visit him someday the photgraphs he sends me are fantastic looking

    Thanks a lot

    1. On your Windows machine, you need to give Unison a place to work from. Right click My Computer, go to Properties and on the Advanced tab there should be a button for Environment Variables. Add a new system variable called “HOME” and set it to a directory on your computer; I just used “C:\” because the directory structures on both my machines are exactly the same. Not sure what will happen syncing between Linux and Windows, as far as where it will put files, but some experimentation should get you on the right track.

      Vancouver Island is very nice; some amazing beaches in the middle of nowhere, giant millennia-old forests, and lots of caves too. There are places in Canada that are more wild and remote than you can believe. In Europe it’s tough to get more than 20 miles from the nearest restaurant! That said, I should get back to Ireland one of these years, I miss it!

    2. Thanks Mike, I had the same problem as Chris and it was the environment variable

  2. Hey Mike,
    This was the thoroughest guide I could found online. Great job!
    I’ve been battling with configuring unison to work between two XP machines for the past day oh so and I’ll appreciate your input.
    I have freeSSHd running on the server machine and I can log in using SSH perfectly. The paths are all set up on the server so if I login to shell using ssh and type “unison -version” I get the right output. However when attempting to test unison with SSH it just gets stuck on “Contacting server…” and stops there, nothing happens.
    I ran it again using debug -all and I got this:
    [remote] Shell connection: ssh (ssh, , -e, none, -l, , -pw, unisont, -server)

    Nothing more.
    I’m at a loss… any suggestions?

    1. Well I never had that problem, so not sure what it could be! But if you can log in to the remote machine with SSH manually, my guess is your local machine’s Unison install can’t find the SSH executable.

      Make sure that you did step 5 above. And when I say make sure the executables are in the path, make sure it’s the system path, not a user one.

    2. I’m getting same error as Opher – if you look at the freesshd.log file it shows that the user has successfully established an SSH connection, but then the log stops there. It’s almost like the command is not being sent or something…

    3. I get the same error as Opher and bbqchickenrobot, would love to know the solution if anyone has one.

    4. As with Opher, bbqchickenrobot, and Steve, I too am experiencing the freezing at “Contacting Server”. I’m on Windows 7 RC1. A solution would help me tremendously.

    5. I have the same problem as well… “Contacting Server” and freeze there… Please help with a solution.

    6. Solution for “Contact Server…” Freeze is to set the HOME environment Variable.

      If HOME Variable dont help check ur FreeSSH Settings.

      Goto SSH Tab and uncheck “Use new console Engine” this helped for me.

      After that Unison rocks!

  3. Just to confirm: unchecking “Use new console Engine” made the difference for me! Thanks!

Comments are closed.