⏳ Three-minute quickstart guide

This short guide will have you downloading and installing Unison and running your first program. There isn't much exposition here and the focus is on getting you up and running as quickly as possible.

Step 1: Install Unison

If you haven't already, please join the #general and #troubleshooting channels on Discord.

We are really hoping that if you are trying out Unison you'll come talk to us, ask questions, and report bugs! We want you to have a welcoming and positive experience when getting started! 😊

Installation options

The current release is for Mac OS X, 64-bit Linux, and Windows users!

Option 1: Installing or updating using Homebrew

First install homebrew if you haven't already.

Then from the command line enter these commands (or better yet, paste them into your console):

brew tap unisonweb/unison
brew install unison-language

This will install the Unison codebase manager executable ucm. If you're upgrading from a previous version, just do brew upgrade unison-language.

Note: if you get prompted for a GitHub username and password at this point, make sure you spelled unisonweb/unison correctly.

Option 2: Install Debian / Ubuntu users

Unison Stable Release

curl http://debian.unison-lang.org/public.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/unison-computing.gpg
echo 'deb [signed-by=/etc/apt/trusted.gpg.d/unison-computing.gpg] http://debian.unison-lang.org/ bookworm main' | sudo tee /etc/apt/sources.list.d/unison-computing.list
sudo apt update
sudo apt install unisonweb
/usr/bin/ucm

Unison Nightly Release

curl http://debian.unison-lang.org/public.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/unison-computing.gpg
echo 'deb [signed-by=/etc/apt/trusted.gpg.d/unison-computing.gpg] http://debian.unison-lang.org/ bookworm nightly' | sudo tee /etc/apt/sources.list.d/unison-computing.list
sudo apt update
sudo apt install unisonweb
/usr/bin/ucm

Option 3: Install manually for Mac and Linux users

Linux

mkdir -p unisonlanguage && cd unisonlanguage
curl -L https://github.com/unisonweb/unison/releases/latest/download/ucm-linux-x64.tar.gz \
	| tar -xz
./ucm

Mac (Intel)

mkdir -p unisonlanguage && cd unisonlanguage
curl -L https://github.com/unisonweb/unison/releases/latest/download/ucm-macos-x64.tar.gz \
  | tar -xz
./ucm

Mac (Apple Silicon)

mkdir -p unisonlanguage && cd unisonlanguage
curl -L https://github.com/unisonweb/unison/releases/latest/download/ucm-macos-arm64.tar.gz \
  | tar -xz
./ucm

Option 4: Install manually for Windows users

Set your default terminal application to “Windows Terminal” for best results. Search for “Terminal” in Settings, or follow this how-to.
Download UCM and extract it to a location of your choosing.
Run ucm.exe 🎉

Option 5: Nix installation

Head to https://github.com/ceedubs/unison-nix/#usage and follow the instructions in the readme there.

Unison Language Server installation

Unison has a Language Server Protocol (LSP) integration! Instructions for downloading and setting up the Unison Language Server are available here.

Step 2: Create your Unison codebase

Run ucm to initialize a Unison codebase in $HOME/.unison. This is where Unison will store function definitions, types, namespaces, and so on.

Step 3: Create the quickstart project

A Unison codebase is subdivided into many projects. Unison projects represent the various libraries, applications, or programs that you might be working on. From the root of your codebase, represented with ., use the project.create command to make a new quickstart project. It will create a main branch for you to work in.

scratch/main> project.create quickstart

You'll see the UCM download the base standard library into a lib namespace. Namespaces help give structure to Unison code because a Unison codebase isn't saved to the file system. You can think of this as our analog to a directory structure. Namespace segments are separated with the . character. A project's dependencies are located in a special namespace called lib. The code for our quickstart project will be simple, so we only need the base library in scope. Check that the base library has been downloaded by running ls lib.base in the UCM.

quickstart/main> ls lib.base

Run your first program

Head to the text editor of your choosing and create a new file called scratch.u in the directory where you launched ucm (so if you launched ucm from ~/myUnisonCode, you'd create ~/myUnisonCode/scratch.u). Add the following code to the file:

myTerm = List.map (x -> x * 10) [1,2,3,4,5,6]
> myTerm

The first line is defining a Unison term called myTerm. This one multiplies every element in a list by 10, using the jsonschema.lib.base.data.List.map function.

The second, beginning with >, is a watch expression.

The ucm monitors all the unison source files in the current directory for changes and evaluates any watch expressions:

quickstart/main>

  I found and typechecked these definitions in ~/myUnisonCode/scratch.u. If you do an `add` or
  `update`, here's how your codebase would change:

    ⍟ These new definitions are ok to `add`:

      myTerm : [Nat]

  Now evaluating any watch expressions (lines starting with `>`)... Ctrl+C cancels.

    2 | > myTerm
          ⧩
          [10, 20, 30, 40, 50, 60]

Congratulations, you ran your first Unison program!

We want to hear from you!

If you have any trouble with the process, or have ideas about how to improve this document, come talk to us in the #troubleshooting Discord channel!