Build and Install Iroha 2
For this tutorial, you will need:
- A working Rust toolchain:
rustcv1.60 and up 
- (Optional) Docker
- (Optional) Docker compose 
Install the Rust Toolchain
This is normally a straightforward process, but we've added troubleshooting details for each stage in case you experience issues with installation process.
The easiest way to get the official
rustup script is to run:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Or, alternatively, you can install
rustup via your operating system’s package manager.
If you know what you're doing, you can also install the Rust toolchain directly, without
If you go with the one-line
curl script, you will be guided through the setup process. Just go with the defaults.
Troubleshooting: Rust Toolchain
Click to expand
Sometimes, things don’t go as planned. Especially if you had
rust on your system a while ago, but didn’t upgrade. A similar problem can occur in Python: XKCD has a famous example of what that might look like:
In the interest of preserving both your and our sanity, make sure that you have the right version of
cargo paired with the right version of
rustc (1.57 and 1.57) respectively. To show the versions, do
cargo -V cargo 1.60.0 (d1fd9fe 2022-03-01)
rustc --version rustc 1.60.0 (7737e0b5c 2022-04-04)
If you have higher versions, you're fine. If you have lower versions, you can run the following command to update it:
rustup toolchain update stable
If you get lower version numbers and you updated the toolchain and it didn’t work… let’s just say it’s a common problem, but it doesn’t have a common solution.
Firstly, you should establish where the version that you want to use is installed:
rustup which rustc rustup which cargo
The user installations of the toolchains are usually in
~/.rustup/toolchains/stable-*/bin/. If that is the case, you should be able to run
rustup toolchain update stable
and that should fix your problems.
Another option is that you have the up-to-date
stable toolchain, but it is not set as the default. Run:
rustup default stable
This can happen if you installed a
nightly version or set a specific Rust version, but forgot to un-set it.
Continuing down the troubleshooting rabbit-hole, we could have shell aliases:
type rustc type cargo
If these point to locations other than the one you saw when running
rustup which *, then you have a problem. Note that it’s not enough to just
alias rustc "~/.rustup/toolchains/stable-*/bin/rustc" alias cargo "~/.rustup/toolchains/stable-*/bin/cargo"
because there is internal logic that could break regardless of how you re-arrange your shell aliases.
The simplest solution would be to remove the versions that you don’t use.
It’s easier said than done, however, since it entails tracking all the versions of rustup installed and available to you. Usually, there are only two: the system package manager version and the one that got installed into the standard location in your home folder when you ran the command in the beginning of this tutorial. For the former, consult your (Linux) distribution’s manual, (
apt remove rust). For the latter, run:
rustup toolchain list
And then, for every
<toolchain> (without the angle brackets of course):
rustup remove <toolchain>
After that, make sure that
results in a command-not-found error, i.e. that you have no active Rust toolchain installed. Then, run:
rustup toolchain install stable
If after all of this work, you still don’t seem to have the right version, then the issue runs deeper.
Install Iroha from GitHub
If you haven’t already, you might want to create a clean folder for Iroha 2, to keep things tidy.
mkdir -p ~/Git
On macOS, if you get
fatal: could not create work tree dir 'iroha': Read-only file system, that’s because the home folder is not a real file system. The fix is to create the
Enter the directory you have just created using
clonethe Iroha git repository into the folder
git clone https://github.com/hyperledger/iroha.git
This will fetch all of Iroha, including Iroha 1, and the
iroha2-devbranch, which we will touch upon later.
Choose the right branch: the main and the latest currently supported monthly release of Iroha.
git checkout iroha2
After you have successfully cloned the Iroha git repository and are on the correct branch, build the Iroha 2 client using:
cargo build -p iroha_client_cli
We take pride in the fact that Iroha is extremely quick to compile. For reference, compiling hyperledger/substrate takes a good part of ten minutes on a modern M1 machine. Iroha, for comparison, compiles in around one minute.
Bring up a minimal network
You can run Iroha directly on bare metal, but we recommend bringing up a network of 4 containerised peers using
Of course, installing Docker might seem like a daunting task, but it allows for reproducible management of configurations, which is oftentimes tricky on bare metal.
On a properly configured docker compose, you should never have to use
sudo. If you do, consider looking into starting the docker dæmon first by running
systemctl enable docker on Linux.
Depending on your set-up, this might either pull the image off of DockerHub, or build the container locally. After this process is complete, you'll be greeted with,
When you're done with test network, just hit
Control + C to stop the containers (
^ + C on Mac).
As we said, you can also try and use the bare metal script. For testing we use
scripts/test_env.sh setup, which will also start a set of Iroha peers. But that network is much harder to monitor, and unless you're well-versed in
killall and reading log files with a proper text editor, we recommend that you don’t go this route.
Unless you have an absolute aversion to
docker, it’s easier to work with, easier to set up, and easier to debug. We try to cater to all tastes, but some tastes have objective advantages.