Install Holochain

This guide will get you set up with the latest ‘blessed’ Holochain developer environment on macOS, Linux, and Windows. Blessed releases are reasonably stable, while in-between releases may have bugs or are meant for internal use. If you’d like to install an in-between release, read our advanced guide.

Hardware Requirements

  • 4GB+ RAM (16GB+ recommended)
  • 4+ CPU (6+ CPU recommended)
  • 30GB+ available disk space
  • Internet connection

Mac / Linux

macOS Requirements

Pre-Installed Software

Special Notes on Catalina

If you are using macOS Catalina you will need to do a workaround. There is an active issue here that may help.

Linux Requirements


Install the Nix Package Manager

We use Nix toolkit to manage the installation of our dev tools. Install the Nix package manager with this command:

curl | sh

You might need to run this command to get the environment setup:

. ~/.nix-profile/etc/profile.d/

Check that it installed correctly:

nix-shell --version

You should see something like:

nix-shell (Nix) 2.3.1

If you’d like to know more about NixOS and why we use it, you can find information on Nix here.

Install Holochain Tools

Now that you have installed Nix, you can run a development shell that contains all the prerequisites, including the correct Rust and Node.js versions and the Holochain tools. This shell won’t interfere with your current system configuration. Run this command:


The first time you run this command it will take some time to download and build, but it will be much faster the next time.

When it’s complete, you will see a new prompt starting with:


Test that Holochain is working by running:

Run in nix-shell

hc --version
holochain --version

You should see something like:

hc 0.0.41-alpha4
holochain 0.0.41-alpha4


You don’t need to worry about updating or uninstalling. When you enter the nix-shell, it checks for the latest blessed release, downloads any updates, and then cleans up the configuration when you exit.


In most cases you can run your editor as normal. However, if you are using an editor integrated development environment (IDE) that needs to communicate with the Rust compiler, then you should launch it from inside the nix-shell. To do this, just open your editor while you are in the nix-shell like:

Run in nix-shell


Next Steps

  1. Read through the Holochain Core Concepts.
  2. Start the Hello Holo Tutorial
  3. Create a new app
  4. Learn more about Holochain development in the Guidebook.
  5. Learn more about Rust and Holochain in the API Reference Documentation,, and the Rust book.
  6. Learn more about Nix as a dev requirement and why we’re using it in the Holonix documentation.

Was this helpful?