Installing cardano-node and cardano-cli from source
This document's current version is relevant for cardano-node release version 8.0.0 (May-2023)
Overview
This guide will show you how to compile and install the cardano-node and cardano-cli into your operating system of choice, directly from the source-code. It will enable you to interact with the Cardano blockchain, including but not limited to sending/receiving transactions, creating NFTs, posting transaction metadata into the blockchain, minting/burning native tokens, creating a stake pool, executing smart contracts, and so much more!
If you want to avoid compiling the binaries yourself, you can download the latest Linux, Mac, Windows versions of cardano-node and cardano-cli from the official IOHK release page.
The components can be built and run on Windows and MacOS, but we recommend that stake pool operators use Linux in production to take advantage of the associated performance advantages.
Prerequisites
To set up the components, you will need:
- Windows, MacOS, or Linux for your operating system
- An Intel or AMD x86 processor with two or more cores, at 1.6GHz or faster (2GHz or faster for a stake pool or relay)
- 24GB of RAM and at least 150GB of free disk space (250GB recommended for future growth)
If intending to connect to Mainnet instance, the requirements for RAM and storage would increase beyond baselines above.
Choose your Platform
Linux
In this section, we will walk you through the process of downloading, compiling, and installing cardano-node and cardano-cli into your Linux-based operating system.
Installing Operating System dependencies
To download the source code and build it, you need the following packages and tools on your Linux system:
- the version control system
git, - the
gccC-compiler, - C++ support for
gcc, - developer libraries for the arbitrary precision library
gmp, - developer libraries for the compression library
zlib, - developer libraries for
systemd, - developer libraries for
ncurses, ncursescompatibility libraries,- the Haskell build tool
cabal, - the GHC Haskell compiler (version
8.10.7or above).
In Redhat, Fedora, and Centos:
sudo yum update -y
sudo yum install git gcc gcc-c++ tmux gmp-devel make tar xz wget zlib-devel libtool autoconf jq -y
sudo yum install systemd-devel ncurses-devel ncurses-compat-libs -y
For Debian/Ubuntu, use the following instead:
sudo apt-get update -y && sudo apt-get upgrade -y
sudo apt-get install automake build-essential pkg-config libffi-dev libgmp-dev libssl-dev libtinfo-dev libsystemd-dev zlib1g-dev make g++ tmux git jq wget libncursesw5 libtool autoconf -y
If you are using a different flavor of Linux, you will need to use the correct package manager for your platform instead of yum or apt-get, and the names of the packages you need to install might differ.
Installing GHC and Cabal
The fastest way to install GHC (Glasgow Haskell Compiler) and Cabal (Common Architecture for Building Applications and Libraries) is to use ghcup.
Use the following command to install ghcup
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
Please follow the instructions and provide the necessary input to the installer.
Do you want ghcup to automatically add the required PATH variable to "/home/ubuntu/.bashrc"? - (P or enter)
Do you want to install haskell-language-server (HLS)? - (N or enter)
Do you want to install stack? - (N or enter)
Press ENTER to proceed or ctrl-c to abort. (enter)
Once complete, you should have ghc and cabal installed to your system.
ghcup will try to detect your shell and ask you to add it to the environment variables. Please restart your shell/terminal after installing ghcup
You can check if ghcup has been installed correctly by typing ghcup --version into the terminal. You should see something similar to the following:
The GHCup Haskell installer, version 0.1.19.2
ghcup will install the latest stable version of ghc. However, as of the time of writing this, Input-Output recommends using ghc 8.10.7. So, we will use ghcup to install and switch to the required version.
ghcup install ghc 8.10.7
ghcup set ghc 8.10.7
ghcup will install the latest stable version of cabal. However, as of the time of writing this, Input-Output recommends using cabal 3.6.2.0. So, we will use ghcup to install and switch to the required version.
ghcup install cabal 3.6.2.0
ghcup set cabal 3.6.2.0
Finally, we check if we have the correct ghc and cabal versions installed.
Check ghc version:
ghc --version
You should see something like this:
The Glorious Glasgow Haskell Compilation System, version 8.10.7
Check cabal version:
cabal --version
You should see something like this:
cabal-install version 3.6.2.0
compiled using version 3.6.2.0 of the Cabal library
Please confirm that the versions you have installed match the recommended versions above. If not, check if you have missed any of the previous steps.
Downloading & Compiling
Let's create a working directory to store the source-code and builds for the components.
mkdir -p $HOME/cardano-src
cd $HOME/cardano-src
Next, we will download, compile and install libsodium.
git clone https://github.com/input-output-hk/libsodium
cd libsodium
git checkout dbb48cc
./autogen.sh
./configure
make
sudo make install
Then we will add the following environment variables to your shell profile. E.G $HOME/.zshrc or $HOME/.bashrc depending on what shell application you are using. Add the following to the bottom of your shell profile/config file so that the compiler can be aware that libsodium is installed on your system.
export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
Once saved, we will then reload your shell profile to use the new variables. We can do that by typing source $HOME/.bashrc or source $HOME/.zshrc (depending on the shell application you use).
We need to install secp256k1 which is required from cardano-node version 1.35.0 onward:
Download and install libsecp256k1:
cd $HOME/cardano-src
git clone https://github.com/bitcoin-core/secp256k1
cd secp256k1
git checkout ac83be33
./autogen.sh
./configure --enable-module-schnorrsig --enable-experimental
make
make check
sudo make install
sudo ldconfig
Now we are ready to download, compile and install cardano-node and cardano-cli. But first, we have to make sure we are back at the root of our working directory:
cd $HOME/cardano-src
Download the cardano-node repository:
git clone https://github.com/input-output-hk/cardano-node.git
cd cardano-node
git fetch --all --recurse-submodules --tags
Switch the repository to the latest tagged commit:
git checkout $(curl -s https://api.github.com/repos/IntersectMBO/cardano-node/releases/latest | jq -r .tag_name)
If upgrading an existing node, please ensure that you have read the release notes on GitHub for any changes.
Configuring the build options
We explicitly use the ghc version that we installed earlier. This avoids defaulting to a system version of ghc that might be newer or older than the one you have installed.
cabal configure --with-compiler=ghc-8.10.7
For some installations you might encounter the following warning:
Warning: The package list for 'cardano-haskell-packages' does not exist. Run 'cabal update' to download it.
Running cabal update will fix this problem, as well as other problems resulting from changes to the package list... so it is generally recommended for each installation even if you don't get this error.
If you are running non x86/x64 platform (eg. ARM) please install and configure LLVM with:
sudo apt install llvm-9
sudo apt install clang-9 libnuma-dev
sudo ln -s /usr/bin/llvm-config-9 /usr/bin/llvm-config
sudo ln -s /usr/bin/opt-9 /usr/bin/opt
sudo ln -s /usr/bin/llc-9 /usr/bin/llc
sudo ln -s /usr/bin/clang-9 /usr/bin/clang
Building and installing the node
We can now build the Haskell-based cardano-node to produce executable binaries.
cabal update
cabal build all
Install the newly built node and CLI commands to the $HOME/.local/bin directory:
mkdir -p $HOME/.local/bin
cp -p "$(./scripts/bin-path.sh cardano-node)" $HOME/.local/bin/
cp -p "$(./scripts/bin-path.sh cardano-cli)" $HOME/.local/bin/
We have to add this line below our shell profile so that the shell/terminal can recognize that cardano-node and cardano-cli are global commands. ($HOME/.zshrc or $HOME/.bashrc depending on the shell application you use)
export PATH="$HOME/.local/bin/:$PATH"
Once saved, reload your shell profile by typing source $HOME/.zshrc or source $HOME/.bashrc (depending on the shell application you use).
Check the version that has been installed:
cardano-cli --version
cardano-node --version
Congratulations, you have successfully installed Cardano components into your Linux system! 🎉🎉🎉
Next, we will talk about how to run cardano-node.
MacOS
In this section, we will walk you through the process of downloading, compiling, and installing cardano-node and cardano-cli into your MacOS-based operating system.
Installing Operating System dependencies
To download the source code and build it, you need the following packages and tools on your MacOS system:
- Xcode - The Apple Development IDE and SDK/Tools
- Xcode Command Line Tools, you can install it by typing
xcode-select --installin the terminal. - Homebrew - The Missing Package Manager for MacOS (or Linux)
Installing Homebrew packages
For the cardano-node and cardano-cli components to compile properly, we will need to install some libraries via brew:
brew install jq
brew install libtool
brew install autoconf
brew install automake
brew install pkg-config
brew install openssl
You will need to install llvm in case you are using M1
brew install llvm@13
Installing GHC and Cabal
The fastest way to install GHC (Glassglow Haskell Compiler) and Cabal (Common Architecture for Building Applications and Libraries) is to use ghcup.
Use the following command to install ghcup
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
Please follow the instructions and provide the necessary input to the installer.
Do you want ghcup to automatically add the required PATH variable to "/home/ubuntu/.bashrc"? - (P or enter)
Do you want to install haskell-language-server (HLS)? - (N or enter)
Do you want to install stack? - (N or enter)
Press ENTER to proceed or ctrl-c to abort. (enter)
Once complete, you should have ghc and cabal installed to your system.
ghcup will try to detect your shell and will ask you to add it to the environment variables. Please restart your shell/terminal after installing ghcup
You can check if ghcup has been installed properly by typing ghcup --version into the terminal. You should see something similar to the following:
The GHCup Haskell installer, version v0.1.17.4
ghcup will install the latest stable version of ghc. However, as of the time writing this, Input-Output recommends using ghc 8.10.7. So, we will use ghcup to install and switch to the required version.
ghcup install ghc 8.10.7
ghcup set ghc 8.10.7
ghcup will install the latest stable version of cabal. However, as of the time of writing this, Input-Output recommends using cabal 3.6.2.0. So, we will use ghcup to install and switch to the required version.
ghcup install cabal 3.6.2.0
ghcup set cabal 3.6.2.0
Finally, we check if we have the correct ghc and cabal versions installed.
Check ghc version:
ghc --version
You should see something like this:
The Glorious Glasgow Haskell Compilation System, version 8.10.7
Check cabal version:
cabal --version
You should see something like this:
cabal-install version 3.6.2.0
compiled using version 3.6.2.0 of the Cabal library
Please confirm that the versions you have installed matches the recommended versions above. If not, check if you have missed any of the previous steps.
Downloading & Compiling
Let's create a working directory to store the source-code and builds for the components.
mkdir -p $HOME/cardano-src
cd $HOME/cardano-src
Next, we will download, compile and install libsodium.
git clone https://github.com/input-output-hk/libsodium
cd libsodium
git checkout dbb48cc
./autogen.sh
./configure
make
sudo make install
Then we will add the following environment variables to your shell profile. E.G $HOME/.zshrc or $HOME/.bashrc depending on what shell application you are using. Add the following to the bottom of your shell profile/config file so the compiler can be aware that libsodium is installed on your system.
export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
If you installed llvm for M1, then you will need to add this too, assuming that your exact llvm version is 13.0.1_2:
export PATH="/opt/homebrew/Cellar/llvm@13/13.0.1_2/bin:$PATH"
llvm installation path might differs based on your installation, if you used default installation, it should be ok. Please check screen after you installed llvm to see this info, if you forgot or lost it, you can just reinstall llvm and then you will see them again.
Once saved, we will then reload your shell profile to use the new variables. We can do that by typing source $HOME/.bashrc or source $HOME/.zshrc (depending on the shell application you use).
We need to install Secp256k1 which is required from 1.35.0 cardano-node version onward:
Download and install libsecp256k1:
cd $HOME/cardano-src
git clone https://github.com/bitcoin-core/secp256k1
cd secp256k1
git checkout ac83be33
./autogen.sh
./configure --enable-module-schnorrsig --enable-experimental
make
make check
sudo make install
Now we are ready to download, compile and install cardano-node and cardano-cli. But first, we have to make sure we are back at the root of our working directory:
cd $HOME/cardano-src
Download the cardano-node repository:
git clone https://github.com/input-output-hk/cardano-node.git
cd cardano-node
git fetch --all --recurse-submodules --tags
Switch the repository to the latest tagged commit:
git checkout $(curl -s https://api.github.com/repos/IntersectMBO/cardano-node/releases/latest | jq -r .tag_name)
If upgrading an existing node, please ensure that you have read the release notes on GitHub for any changes.
Configuring the build options
We explicitly use the ghc version that we installed earlier. This avoids defaulting to a system version of ghc that might be newer or older than the one you have installed.
cabal configure --with-compiler=ghc-8.10.7
For some installations you might encounter the following warning: Warning: The package list for 'cardano-haskell-packages' does not exist. Run 'cabal update' to download it.. The warning is self-explanatory and you will need to run cabal update before moving on.
You will need to run following commands on M1, those commands will set some cabal related options before building
echo "package trace-dispatcher" >> cabal.project.local
echo " ghc-options: -Wwarn" >> cabal.project.local
echo "" >> cabal.project.local
echo "package HsOpenSSL" >> cabal.project.local
echo " flags: -homebrew-openssl" >> cabal.project.local
echo "" >> cabal.project.local
Building and installing the node
cabal update
cabal build all
More recent versions of MacOS seems to install openssl in a different location than expected by default. If you have installed openssl via homebrew and encounter the following build error:
Failed to build HsOpenSSL-0.11.7.2. The failure occurred during the configure
step.
[1 of 1] Compiling Main (...)
Linking .../dist-newstyle/tmp/src-75805/HsOpenSSL-0.11.7.2/dist/setup/setup ...
Configuring HsOpenSSL-0.11.7.2...
setup: Can’t find OpenSSL library
You'll most likely need to add relevant symlinks as follows:
sudo mkdir -p /usr/local/opt/openssl
sudo ln -s /opt/homebrew/opt/openssl@3/lib /usr/local/opt/openssl/lib
sudo ln -s /opt/homebrew/opt/openssl@3/include /usr/local/opt/openssl/include
This is a wart of the HsOpenSSL library wrapper, and using classic methods such as setting LDFLAGS & CPPFLAGS, or using --extra-include-dirs and --extra-lib-dirs won't work properly.
Install the newly built node and CLI to the $HOME/.local/bin directory:
mkdir -p $HOME/.local/bin
cp -p "$(./scripts/bin-path.sh cardano-node)" $HOME/.local/bin/
cp -p "$(./scripts/bin-path.sh cardano-cli)" $HOME/.local/bin/
We have to add this line below our shell profile so that the shell/terminal can recognize that cardano-node and cardano-cli are global commands. ($HOME/.zshrc or $HOME/.bashrc depending on the shell application you use)
export PATH="$HOME/.local/bin/:$PATH"
Once saved, reload your shell profile by typing source $HOME/.zshrc or source $HOME/.bashrc (depending on the shell application you use).
Check the version that has been installed:
cardano-cli --version
cardano-node --version
Congratulations, you have successfully installed Cardano components into your MacOS system! 🎉🎉🎉
Next, we will talk about how to run cardano-node.
Windows
Currently, the Windows installation guide is still in progress. In the meantime, we recommend using WSL (Windows Subsystem for Linux) to get a Linux environment on top of Windows. Once installed, you can use the Linux guide to install and run cardano-node within WSL.