Upgrading a Node
🎉 Introduction​
Input-Output (IOHK) regularly releases new versions of Cardano Node via the official GitHub repository. Carefully review release notes available in the repository for new features, configurations, 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 instance to the latest version. Complete the following procedures on each block producer and relay node comprising your stake pool configuration as needed to complete the upgrade.
For instructions on upgrading your stake pool to a previous Cardano Node version, see Appendix F: Archive.
Setting GHC and Cabal Versions ​
For each Cardano Node release, Input-Output recommends compiling binaries using specific versions of GHC and Cabal. 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 | Cardano CLI Version | GHC Version | Cabal Version |
|---|---|---|---|---|
| February 2026 | 10.5.4 | 10.11.0.0 | 9.6.7 | 3.12.1.0 |
To set GHCup, GHC and Cabal versions using a graphical user interface, type the following command using a terminal window:
ghcup tui
To upgrade the GHCup installer for GHC and Cabal to the latest version using the command line, type:
ghcup upgrade
ghcup --version
To install other GHC versions using the command line:
- 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 using the command line:
- 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
Upgrading Shared Libraries​
Compare the versions of shared libraries appearing in the Installing Shared Libraries topic with the versions installed on each computer hosting a Cardano Node instance in your stake pool configuration. If the versions installed on computers in your stake pool configuration are different, then follow the procedures as needed to upgrade shared libraries.
Updating Configuration Files​
A new Cardano Node release may revise existing configuration files and/or introduce additional configuration files. If configuration files are revised or new configuration files are introduced, then you need to download and implement the latest configuration files when upgrading a node.
To download and install the latest Cardano Node configuration files:
- To stop an instance of Cardano Node, type the following command in a terminal window where
<CardanoServiceName>is the name of the systemd service running Cardano Node:
sudo systemctl stop <CardanoServiceName>.service
If you follow the CoinCashew instructions for Automating Cardano Node Startup, then <CardanoServiceName> is cardano-node
2. To back up the configuration files that your node currently uses, type the following commands as appropriate where <ConfigurationFileFolder> is the path to the folder where the configuration files are located and <ConfigFileName> is config-bp on your block-producing node and config on all your relay nodes:
cd <ConfigurationFileFolder>
mv <ConfigFileName>.json <ConfigFileName>.bak
mv topology.json topology.bak
mv peer-snapshot.json peer-snapshot.bak
mv checkpoints.json checkpoints.bak
If you follow the CoinCashew instructions for Downloading Configuration Files, then <ConfigurationFileFolder> is $NODE_HOME If needed, you can also use the environment variable $NODE_CONFIG to indicate the mainnet environment 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. In The Cardano Operations Book, in the left navigation click the name of the environment that the node you are upgrading uses. Click the links to download the following configuration files to the folder where you created backups of your current configuration files in step 2:
config.jsonif you are upgrading a relay nodeconfig-bp.jsonif you are upgrading a block-producing nodetopology.jsonpeer-snapshot.jsoncheckpoints.json
If you want to download 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 config*.bak and topology.bak configuration file backups that you created in step 2 to the respective configuration file that you downloaded in step 4.
The config*.json file contains hashes for the byron-genesis.json, shelley-genesis.json, alonzo-genesis.json and conway-genesis.json files using the ByronGenesisHash, ShelleyGenesisHash, AlonzoGenesisHash and ConwayGenesisHash keys, respectively. Therefore, do NOT manually edit the *genesis.json files.
Installing New Cardano Binaries ​
You can install pre-built Cardano Node binaries available for download from the Cardano Node GitHub repository, or you can download the source code and compile the binaries yourself.
Using Pre-built Binaries​
To install pre-built Cardano Node binaries:
1. To create a temporary path to store the pre-built binaries, type:
mkdir ~/tmp2
cd ~/tmp2
2. Using a Web browser, visit the Releases page for the Cardano Node GitHub repository, and then scroll down to the Assets section for the Cardano Node release you want to install. Right-click the archive containing the binaries that you want to install, and then click Copy Link
3. To download the binaries, type the following commands where <BinaryURL> is the link that you copied in step 2:
wget <BinaryURL>
4. To extract the archive that you downloaded in step 3, type:
tar -xvf ./cardano*.gz
5. To install the new node and cli binaries, type:
sudo mv ~/tmp2/bin/cardano-cli /usr/local/bin/
sudo mv ~/tmp2/bin/cardano-node /usr/local/bin/
6. To delete the temporary folder, type:
cd ..
rm -rf ~/tmp2
7. Complete the upgrade.
Compiling the Binaries​
To build binaries for a new Cardano Node version:
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 https://github.com/IntersectMBO/cardano-node.git ./<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:
# Ensure that development headers for the libsodium cryptographic library are NOT installed on the local computer
sudo apt remove libsodium-dev
# 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 https://api.github.com/repos/IntersectMBO/cardano-node/releases/latest | jq -r .tag_name)
# Adjust the project configuration to disable optimization and use the recommended compiler version
cabal configure -O0 -w ghc-<GHCVersionNumber>
# Compile the cardano-node and cardano-cli packages found in the current directory
cabal build all
cabal build 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:
$(./scripts/bin-path.sh cardano-node) --version
$(./scripts/bin-path.sh cardano-cli) --version
To install the binaries that you compiled:
- If 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 -p "$(./scripts/bin-path.sh cardano-node)" <DestinationPath>/cardano-node
sudo cp -p "$(./scripts/bin-path.sh cardano-cli)" <DestinationPath>/cardano-cli
If you follow the CoinCashew instructions for Compiling Cardano Node, then <DestinationPath> is /usr/local/bin
Completing the Upgrade​
To finish upgrading Cardano Node binaries:
1. To verify that you installed the new Cardano Node binaries successfully, type:
cardano-node version
cardano-cli version
2. To finish the upgrade process, start the Cardano Node systemd service.
sudo systemctl start cardano-node
3. 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 ledger residing on the local computer. The task of replaying the ledger may require hours to complete.
For details on monitoring your node, see the section Verifying the Upgrade.
4. Copy the new cardano-cli binary to the air-gapped, offline computer that you use to sign transactions for your stake pool.
Verifying the Upgrade​
To verify that the upgrade is successful, open a dashboard or follow the Cardano Node log.
journalctl -fu cardano-node
Congratulations on completing the upgrade! ✨
Troubleshooting​
If your upgrade is unsuccessful, then refer to the topics Deleting the Blockchain Ledger and Resetting a Cardano Node Installation, as needed.