Quick Start

Last updated: December 6, 2018


Welcome to the Quick Start guide for getting started with Holochain development. It will guide you through installation, and also point you to a great tutorial for getting started coding.


Step One

Testing of Holochain apps is done in Javascript, executed by Nodejs. To run tests, you'll need Nodejs installed. Nodejs must be version 8 or higher to work. If you don't have it installed already, you can find great installation instructions here: https://nodejs.org

Step Two

In the future, you will be able to use a variety of languages to write Holochain applications. While the WebAssembly API is still being defined the only "HDK" library available, which simplifies Holochain development, is for Rust. Rust must be installed to your computer to develop with Holochain, and it must be the "nightly" toolchain. Platform specific instructions for installation follow:

For Mac and Linux
In a terminal, run:

curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain nightly

For Windows
Go to https://rustup.rs and follow installation instructions. Once you have rust successfully installed, you need to install the "nightly" toolchain of rust. This means having the latest version of the tools, which are required for working with Holochain. In a terminal, run:

rustup toolchain install nightly

rustup default nightly

Step Three

Since Holochain code needs to be in WebAssembly, the Rust compilation "target" for WebAssembly is required. This just means that the Rust toolchain knows how to compile Rust code to WebAssembly. You will likely need to restart your terminal, or open a new one, before being able to run the following command. In a terminal, run:

rustup target add wasm32-unknown-unknown

Step Four

Being a P2P networking framework, Holochain utilizes a "distributed messaging" library internally called ZeroMQ. For the time being (it is hoped to change this in the future), this must be installed on your computer as well before Holochain can run. The version number that you install must be 4.1 or higher.

Mac and Linux

The most update and useful installation instructions for ZMQ are maintained here.


If you are on Windows (only 64 bit machines supported), for now, just download this file, which is a prebuilt ZMQ library.

If you encounter issues with this, please discuss here.

Step Five

The last thing to install is the Holochain command line tools.
Go to GitHub and download the appropriate release for your system.

Once you've downloaded it, unpack it, RENAME it "hc" and move the resulting folder to a directory on your computer where you'd like to keep these files long term. As a default, lets assume that it can be this folder called "hc", right under your $HOME or %USERPROFILE% (your user) directory. Now we will have to add this directory to your PATH variable, so that the binary becomes available within your command line. The instructions for this differ, depending on your platform.

Mac and Linux

If you DO NOT have a shell profile file, follow ALL these instructions in your terminal. If you know about shell profiles, and have one, just do steps 4 and 5

1. This changes directories to your $HOME directory.

cd ~

2. This creates a file called ".bash_profile" in your $HOME directory, if it didn't exist.

touch .bash_profile

3. This opens that file in some text editor on your computer.

open .bash_profile

4. In your editor, add the following to .bash_profile, and save it. If you used a different path than $HOME/hc for your folder, use that instead of $HOME/hc in the line that follows.

export PATH="$HOME/hc:$PATH"

5. This refreshes your terminal so that it can access the binary in the folder that you just added to your $PATH variable.

source .bash_profile


To complete the ZMQ process, first of all, please move the file "libzmq-v140-mt-4_2_0.dll" that you downloaded into the same "hc" folder as the other files.

In your Control Panel, select System>Advanced system settings>Environment Variables... and under System Variables do the following:

If you used a different path than %USERPROFILE%/hc for your folder, use that instead of %USERPROFILE%/hc in the instruction that follows.

Double-click "Path", and in the window that pops up add the following entry:


Once you've done this, be sure to open up a new command line window, before proceeding.

Step Six

Once the steps for your platform are complete, to confirm that you have the Holochain command line tools installed, try running the following command:

hc --version

To read about the commands, and how to get started using them, check out the README for the "hc" command line tools.


A tutorial for getting started coding with the 0.0.2 version of Holochain is available, and is a great place to learn how to build with Holochain now that it's installed! Check it out here