Ask or search…
Comment on page

Upgrading a Node


If you want to support this free educational Cardano content or found the content helpful, visit to find our donation addresses. Much appreciated in advance.
Technical writing by Change Pool [CHG]
Input-Output (IOHK) regularly releases new versions of Cardano Node via the cardano-node GitHub repository. Carefully review release notes available in the repository for new features, known issues, technical specifications, related downloads, documentation, changelogs, assets and other details of each new release.
To receive notifications related to activity in the Cardano Node GitHub repository, configure Watch functionality.
The Upgrading a Node topic describes how to upgrade a Cardano node to the latest version. Complete the following procedures on each block producer and relay node comprising your stake pool as needed to complete the upgrade.
For instructions on upgrading your stake pool to a previous Cardano version, see the archive.

Upgrading Third-party Software


If you use CNCLI command line utilities developed by the Cardano Community, then upgrade to the latest version if a newer version is available.
Do not confuse the Cardano Community's CNCLI utilities with the companion script for stake pool operators maintained by Guild Operators.
To upgrade the Cardano Community's CNCLI binary:
  1. 1.
    In a terminal window, type the following commands:
RELEASETAG=$(curl -s | jq -r .tag_name)
VERSION=$(echo ${RELEASETAG} | cut -c 2-)
echo "Installing release ${RELEASETAG}"
curl -sLJ${RELEASETAG}/cncli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz -o /tmp/cncli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz
sudo tar xzvf /tmp/cncli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz -C /usr/local/bin/
2. To confirm that the new version of the CNCLI binary is installed, type:
cncli -V
If the command displays the latest version number, then the upgrade is successful.

Guild LiveView

Guild Operators maintains a set of tools to simplify operating a Cardano stake pool, including Guild LiveView. If you use the gLiveView script, then ensure that you are using the latest version prior to upgrading your Cardano node.
In the Common env file for Guild Operator scripts, by default the UPDATE_CHECK user variable is set to check for updates to scripts when you start If your implementation displays the message Checking for script updates when gLiveView starts and you install available updates when prompted, then you do NOT need to complete the following procedure.
To upgrade the Guild LiveView tool manually:
  1. 1.
    To back up existing Guild LiveView script files, type the following commands where <gLiveViewFolder> is the folder where the script is located on your computer:
cd <gLiveViewFolder>
mv env env.bak
If you follow the Coin Cashew instructions for Starting the Nodes, then you can type $NODE_HOME to replace
2. To download the latest Guild LiveView script files, type:
curl -s -o
curl -s -o env
3. To set file permissions on the file that you downloaded in step 2, type:
chmod 755
4. To set the CONFIG and SOCKET user variables in the env file that you downloaded in step 2, type:
sed -i env \
-e "s/\#CONFIG=\"\${CNODE_HOME}\/files\/config.json\"/CONFIG=\"\${NODE_HOME}\/mainnet-config.json\"/g" \
-e "s/\#SOCKET=\"\${CNODE_HOME}\/sockets\/node0.socket\"/SOCKET=\"\${NODE_HOME}\/db\/socket\"/g"
For details on setting the NODE_HOME environment variable, see the topic Installing Cabal and GHC
5. As needed to configure Guild LiveView for your stake pool, use a text editor to transfer additional user variable definitions from the env.bak file that you created in step 1 to the env file that you downloaded in step 2.
6. To test the upgrade, type:
If the upgrade is successful, then the terminal window displays the Guild LiveView dashboard having the version number of the latest release.

Setting GHC and Cabal Versions

For each Cardano Node release, Input-Output recommends compiling binaries using specific versions of GHC and Cabal. For example, refer to Installing cardano-node and cardano-cli from source in the Cardano Developer Portal to determine the GHC and Cabal versions required for the current Cardano Node release. Table 1 lists GHC and Cabal version requirements for the current Cardano Node release.
Table 1 Current Cardano Node Version Requirements
Release Date
Cardano Node Version
GHC Version
Cabal Version
May 9, 2023
To upgrade the GHCup installer for GHC and Cabal to the latest version:
  • In a terminal window, type:
ghcup upgrade
ghcup --version
To install other GHC versions:
  • In a terminal window, type the following commands where <GHCVersionNumber> is the GHC version that you want to install and use:
ghcup install ghc <GHCVersionNumber>
ghcup set ghc <GHCVersionNumber>
ghc --version
To install other Cabal versions:
  • In a terminal window, type the following commands where <CabalVersionNumber> is the Cabal version that you want to install and use:
ghcup install cabal <CabalVersionNumber>
ghcup set cabal <CabalVersionNumber>
cabal --version
To set GHCup, GHC and Cabal versions using a graphical user interface, type ghcup tui in a terminal window.
To update Libsodium:
As of version 8.0.0, a new version of libsodium is required.
cd $HOME/git
git clone
cd libsodium
git checkout dbb48cc
make check
sudo make install

Downloading New Configuration Files

A new Cardano Node release may include updated configuration files. If configuration files are updated for a release, then you need to download and install the new configuration files when you upgrade a node.
To download and install new Cardano Node configuration files:
  1. 1.
    To stop your Cardano node, type the following command in a terminal window where <CardanoServiceName> is the name of the systemd service running your Cardano node:
sudo systemctl stop <CardanoServiceName>.service
If you follow the Coin Cashew instructions for Creating Startup Scripts, then <CardanoServiceName> is cardano-node
2. To back up the configuration files that your node currently uses, type the following commands where <ConfigurationFileFolder> is the path to the folder where the configuration files are located:
cd <ConfigurationFileFolder>
mv mainnet-config.json mainnet-config.bak
mv mainnet-byron-genesis.json mainnet-byron-genesis.bak
mv mainnet-shelley-genesis.json mainnet-shelley-genesis.bak
mv mainnet-alonzo-genesis.json mainnet-alonzo-genesis.bak
mv mainnet-topology.json mainnet-topology.bak
If you follow the Coin Cashew instructions for Preparing Configuration Files, then <ConfigurationFileFolder> is $HOME/cardano-my-node Alternately, you can type $NODE_HOME If needed, you can also use the environment variable $NODE_CONFIG to indicate the mainnet cluster in configuration file names.
3. Using a Web browser, navigate to the Cardano Node GitHub repository, then browse to the latest release, then click to expand the Downloads dropdown list in the Technical Specification section of the release notes, and then click the Configuration Files link.
4. On the Cardano Configurations page, click the following links to download configuration files for the mainnet cluster to the folder where you created backups of your current configuration files in step 2: config, byronGenesis, shelleyGenesis, alonzoGenesis, conwayGenesis and topology
As of version 8.0.0, you need to download a new config file, conway-genesis.json
cd <ConfigurationFileFolder>
Then, verify mainnet-config.json contains the two lines additional lines:
"ConwayGenesisFile": "conway-genesis.json",
"ConwayGenesisHash": "f28f1c1280ea0d32f8cd3143e268650d6c1a8e221522ce4a7d20d62fc09783e1",
If you want to download new configuration files using the command line, then navigate to the folder where you created backups of your current configuration files in step 2 using a terminal window, and then type the following command where <ConfigurationFileURL> is the URL for the configuration file that you want to download: wget <ConfigurationFileURL>
5. Using diff or a similar file comparison utility, identify and copy customizations as needed from the backup configuration files that you created in step 2 to each new configuration file that you downloaded in step 4.

Installing New Cardano Binaries

  1. 1.
    Either build the latest binaries or download pre-built binaries from IOHK.
Downloading pre-built binaries from IOHK
  1. 1.
    Create a temporary path to store the pre-built binaries.
mkdir ~/tmp2
cd ~/tmp2
Visit the official Github to determine the latest cardano-node linux binaries link, located under Downloads > Static Binaries > Linux.
  1. 2.
    Download the latest static binaries for Linux. Update below URL with the latest link before continuing.
  1. 3.
    Un-tar the archive.
tar -xvf cardano*.gz
  1. 4.
    Install the new node and cli binaries.
sudo mv ~/tmp2/cardano-cli /usr/local/bin/
sudo mv ~/tmp2/cardano-node /usr/local/bin/
  1. 5.
    Clean up temporary path.
rm -rf ~/tmp2
Building Cardano Node Binaries
To build binaries for a new Cardano Node version:
  1. 1.
    To create a clone of the Cardano Node GitHub repository, type the following commands in a terminal window on the computer you want to upgrade where <NewFolderName> is the name of a folder that does not exist:
# Navigate to the folder where you want to clone the repository
cd $HOME/git
# Download the Cardano Node repository to your local computer
git clone ./<NewFolderName>
Cloning the GitHub repository to a new folder allows you to roll back the upgrade, if needed, by re-installing on your computer the cardano-node and cardano-cli binaries from a folder where you compiled a previous version of Cardano Node packages.
2. To build Cardano Node binaries using the source code that you downloaded in step 1, type the following commands where <NewFolderName> is the name of the folder you created in step 1 and <GHCVersionNumber> is the GHC version that you set in the section Setting GHC and Cabal Versions:
# Navigate to the folder where you cloned the Cardano Node repository
cd $HOME/git/<NewFolderName>
# Update the list of available packages
cabal update
# Download all branches and tags from the remote repository
git fetch --all --recurse-submodules --tags
# Switch to the branch of the latest Cardano Node release
git checkout $(curl -s | jq -r .tag_name)
# Adjust the project configuration to disable optimization and use the recommended compiler version
cabal configure -O0 -w ghc-<GHCVersionNumber>
# Append the cabal.project.local file in the current folder to avoid installing the custom libsodium library
echo -e "package cardano-crypto-praos\n flags: -external-libsodium-vrf" >> cabal.project.local
# Compile the cardano-node and cardano-cli packages found in the current directory
cabal build cardano-node cardano-cli
The time required to compile the cardano-node and cardano-cli packages may be a few minutes to hours, depending on the specifications of your computer.
3. When the compiler finishes, to verify the version numbers of the new cardano-node and cardano-cli binaries type:
$(find ./dist-newstyle/build -type f -name "cardano-node") version
$(find ./dist-newstyle/build -type f -name "cardano-cli") version
To install new cardano-node and cardano-cli binaries:
  1. 1.
    If your Cardano node is running, then type the following command to stop the node where <CardanoServiceName> is the name of the systemd service running your node:
sudo systemctl stop <CardanoServiceName>.service
2. To replace the existing cardano-node and cardano-cli binaries, type the following commands where <DestinationPath> is the absolute file path to the folder where you install Cardano Node binaries on your local computer:
sudo cp $(find ./dist-newstyle/build -type f -name "cardano-node") <DestinationPath>/cardano-node
sudo cp $(find ./dist-newstyle/build -type f -name "cardano-cli") <DestinationPath>/cardano-cli
If you follow the Coin Cashew instructions for Compiling Source Code, then <DestinationPath> is /usr/local/bin
2. To verify that you installed the new Cardano Node binaries successfully, type:
cardano-node version
cardano-cli version
3. Restart your Cardano node systemd service to finish the upgrade process.
sudo systemctl restart cardano-node
4. Optionally, to install the latest versions of all previously installed packages on your computer, and then reboot the computer, type:
sudo apt-get update && sudo apt-get upgrade -y && sudo reboot
Upgrading to a new Cardano Node version may require replaying the copy of the blockchain residing on the local computer. The task of replaying the blockchain may require hours to complete.
To monitor your node, type the command journalctl -fu cardano-nodein a terminal window.
6. Copy the new cardano-cli binary to the air-gapped, offline computer that you use to sign transactions for your stake pool.
7. On your air-gapped, offline computer, ensure libsecp256k1 was installed.

Verifying the Upgrade

To verify that the upgrade is successful, open gLiveView, journalctl logs or Grafana dashboard.
journalctl -fu cardano-node
After an upgrade, starting a node may take up to a few hours. Be patient.
Congrats on completing the update.
Did you find our guide useful? Send us a signal with a tip and we'll keep updating it.
It really energizes us to keep creating the best crypto guides.
Use to find our donation addresses.
Any feedback and all pull requests much appreciated.
Hang out and chat with our stake pool community on Telegram @


If your upgrade is unsuccessful, then try Fixing a Corrupt Blockchain and Resetting an Installation, as needed.