Skip to main content

Installing cardano-node

version reference

This document was written in May 2026 for the current stable release 11.0.1. Always check the releases page for the latest version before installing.

Cardano Node Course

For a comprehensive video course on the Cardano Node and CLI as an end user, stake pool operator, and governance actor, see the Cardano Node Course.

Hardware requirements​

NetworkCPU CoresFree RAMFree storage
Mainnet224GB300GB minimum (500GB+ recommended — chain grows over time)
Testnet24GB20GB

Stake pool block producers should run Linux. The node runs on macOS and Windows but those platforms are not used in production.

Installation​

Choose whichever method fits your environment. For block producers, building from source lets you verify the binary matches the code.

Release binaries — quickest, no build required

Each GitHub release ships statically-linked tarballs for Linux amd64 and arm64, built by the same Nix musl pipeline as the Nix build below.

VERSION=11.0.1  # check releases page for latest
wget https://github.com/IntersectMBO/cardano-node/releases/download/${VERSION}/cardano-node-${VERSION}-linux.tar.gz
tar -xzf cardano-node-${VERSION}-linux.tar.gz -C ~/.local/

The tarball unpacks into bin/ and share/ (configuration files for mainnet, preprod, and preview). Ensure ~/.local/bin is on your $PATH.

Security consideration

Pre-built binaries require trusting the build pipeline. For block producers holding hot keys, many operators prefer building from source so they can verify the binary themselves. The Nix build below produces the same static artifacts reproducibly.

Docker / GHCR images

Container images for cardano-node, cardano-tracer, and cardano-submit-api are published to the GitHub Container Registry:

VERSION=11.0.1  # check releases page for latest
docker pull ghcr.io/intersectmbo/cardano-node:${VERSION}

See the cardano-node packages page for all available tags.

To build and load your own image from the upstream flake instead of pulling:

VERSION=11.0.1  # check releases page for latest
# Build the node image (outputs a tarball)
nix build github:IntersectMBO/cardano-node/${VERSION}#dockerImage/node
# Load it into Docker
docker load -i result
Security consideration

Docker images require trusting the build pipeline, the base image, and the container runtime. For block producers holding hot keys, many operators prefer building from source so they can verify the binary themselves — building the image yourself with nix build above produces a reproducible image from the same pipeline used for official releases. If you do run a containerised node, do not mount key files or any sensitive host paths into the container.

Build with Nix — recommended for operators who want a verified build

If you don't have Nix installed, use the Determinate Systems installer — it enables flakes by default and handles uninstallation cleanly.

Set up the IOG binary cache before building. Without it, Nix will compile GHC and all Haskell dependencies from scratch, which can take many hours. Follow the IOGX Nix setup guide.

Build the statically-linked musl release tarball directly from the upstream flake — no clone needed:

x86_64 (amd64):

VERSION=11.0.1  # check releases page for latest
nix build github:IntersectMBO/cardano-node/${VERSION}#hydraJobs.x86_64-linux.musl.cardano-node-linux

aarch64 (arm64):

VERSION=11.0.1  # check releases page for latest
nix build github:IntersectMBO/cardano-node/${VERSION}#hydraJobs.aarch64-linux.musl.cardano-node-linux

Replace 11.0.1 with the version you want. result/ will contain a tarball with the same layout as the release binaries — extract it the same way:

tar -xzf result/*.tar.gz -C ~/.local/

NixOS deployments​

The flake exposes a nixosModules.cardano-node output for managing the node declaratively as a systemd service with all configuration in Nix. See nix/nixos-module.nix for the available module options.

Build with GHCup / cabal — for systems without Nix

Building with cabal requires manually installing several C libraries that Nix would otherwise handle. Use the Nix method unless you have a specific reason not to.

System libraries​

Check the cardano-node repository for the GHC and cabal versions required by the release you're building. For 11.0.1: GHC 9.6.7, cabal 3.12.1.0.

sudo apt-get update -y
sudo apt-get install automake build-essential pkg-config libffi-dev libgmp-dev libssl-dev libncurses-dev libsystemd-dev zlib1g-dev make g++ tmux git jq wget libtool autoconf liblmdb-dev libsnappy-dev protobuf-compiler liburing-dev -y

Installing GHCup, GHC, and cabal​

Install GHCup using its installer, then install the required toolchain versions:

ghcup install ghc 9.6.7 --set
ghcup install cabal 3.12.1.0 --set

Verify you're using the GHCup-managed tools (not a system installation):

which cabal  # should return /home/<user>/.ghcup/bin/cabal

C library dependencies​

Cardano requires specific versions of sodium, secp256k1, and blst. Determine the correct versions from the node's own lock file:

CARDANO_NODE_VERSION='11.0.1'
IOHKNIX_VERSION=$(curl -s https://raw.githubusercontent.com/IntersectMBO/cardano-node/$CARDANO_NODE_VERSION/flake.lock | jq -r '.nodes.iohkNix.locked.rev')
caution

These three libraries must match the versions pinned in iohkNix for the specific node release. Wrong versions cause cryptographic failures at runtime.

Create a working directory and build each library:

mkdir -p ~/src
cd ~/src

sodium (Cardano uses a custom fork with additional cryptographic functions):

SODIUM_VERSION=$(curl -s https://raw.githubusercontent.com/input-output-hk/iohk-nix/$IOHKNIX_VERSION/flake.lock | jq -r '.nodes.sodium.original.rev')
git clone https://github.com/intersectmbo/libsodium
cd libsodium && git checkout $SODIUM_VERSION
./autogen.sh && ./configure
make && sudo make install
cd ~/src

secp256k1:

SECP256K1_VERSION=$(curl -s https://raw.githubusercontent.com/input-output-hk/iohk-nix/$IOHKNIX_VERSION/flake.lock | jq -r '.nodes.secp256k1.original.ref')
git clone --depth 1 --branch ${SECP256K1_VERSION} https://github.com/bitcoin-core/secp256k1
cd secp256k1
./autogen.sh && ./configure --enable-module-schnorrsig --enable-experimental
make && sudo make install
cd ~/src

blst:

BLST_VERSION=$(curl -s https://raw.githubusercontent.com/input-output-hk/iohk-nix/$IOHKNIX_VERSION/flake.lock | jq -r '.nodes.blst.original.ref')
git clone --depth 1 --branch ${BLST_VERSION} https://github.com/supranational/blst
cd blst && ./build.sh
cat > libblst.pc << EOF
prefix=/usr/local
exec_prefix=\${prefix}
libdir=\${exec_prefix}/lib
includedir=\${prefix}/include

Name: libblst
Description: Multilingual BLS12-381 signature library
URL: https://github.com/supranational/blst
Version: ${BLST_VERSION#v}
Cflags: -I\${includedir}
Libs: -L\${libdir} -lblst
EOF
sudo cp libblst.pc /usr/local/lib/pkgconfig/
sudo cp bindings/blst_aux.h bindings/blst.h bindings/blst.hpp /usr/local/include/
sudo cp libblst.a /usr/local/lib
sudo chmod u=rw,go=r /usr/local/{lib/{libblst.a,pkgconfig/libblst.pc},include/{blst.{h,hpp},blst_aux.h}}
cd ~/src

Add the library paths to your shell profile (~/.bashrc or ~/.zshrc) and reload it:

export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
Dynamic linker

On some distributions the node binary links against the right libsodium.so but the dynamic linker loads the wrong one at runtime. If you suspect this, check with pldd on the running process — if it shows the wrong library path, run ldconfig.

Building the node​

VERSION=11.0.1  # check releases page for latest
cd ~/src
git clone https://github.com/intersectmbo/cardano-node.git
cd cardano-node
git switch -d tags/${VERSION}

Pin the GHC version to avoid accidentally using a system-installed GHC:

echo "with-compiler: ghc-9.6.7" >> cabal.project.local

On Apple Silicon, add these 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

Build:

cabal update
cabal build exe:cardano-node cardano-cli

Copy the built binaries to your $PATH:

mkdir -p ~/.local/bin
cp -p "$(cabal list-bin cardano-node)" ~/.local/bin/
cp -p "$(cabal list-bin cardano-cli)" ~/.local/bin/

We copy rather than use cabal install because cabal install strips the git revision from the binary, breaking cardano-node --version output.

Verify:

cardano-node --version
cardano-cli --version
Ledger state snapshots on upgrade

If the ledger serialization format changed between versions, the node will delete snapshots in db/ledger/ on first startup. Back those up before upgrading if you want to be able to roll back.