Skip to main content
Version: 2.0.3

Upgrading and downgrading Prysm

This section outlines the step-by-step process for how to keep Prysm up-to-date, how to downgrade versions, and some security recommendations for stakers regarding updates.

Installing Prysm#

There are three main ways of installing Prysm:

Recommended versions#

Regardless of your installation method, we always recommend you are running the latest version in our releases page on Github, specified in semver format such as v1.0.0-beta.1. You can check your Prysm version by running your beacon node or validator with the --version flag. For example, if using prysm.sh to run the beacon node, you would run:

prysm.sh beacon-chain --version

You should see a message that says Using prysm version and prints the version number. If you have set environment variable USE_PRYSM_VERSION to a specific version, the prysm.sh script will not automatically update your client. Unset the environment variable or set it to a recent version, then restart your processes with prysm.sh.

Double Check Running Processes

Running prysm.sh beacon-chain --version may not reflect the version of the currently running process. After verifying the version with prysm.sh, be sure to check that your process was restarted recently to pick up the latest version. Alternatively, you can query the /metrics page for the prysm_version value on port 8080 or 8081 for the beacon-chain node and validator node, respectively.

Always Run a Stable Release

If you are running docker or building from source, we never recommend running from the :latest docker tag nor the master branch of Prysm. we always recommend using :stable if running Docker, or using a specific version tag from our latest releases. Likewise for Bazel, we recommend doing a git checkout COMMIT_HASH where COMMIT_HASH is for our latest release version

How to subscribe for updates#

Prysm has two official channels for release updates: our Discord and our mailing list. All releases will be notified via those channels, and we always recommend reading our release notes on Github in case there are breaking changes to running a node. Our team avoids breaking changes whenever possible, and we will make it clear in our release notes or in releases ahead of time that breaking changes are coming.

How to securely upgrade Prysm#

Updating in Prysm can incur a few seconds downtime depending on your installation method. Every validator will attest once per epoch (every 6.4 minutes on average), while proposals are more rare. To check your next assigned slot to attest or propose, we recommend checking your validator on beaconcha.in. Although missing a single validator duty is not a big deal, you can wait to update right after you attest or propose for optimal performance.

Missing a single validator duty is not a big deal

Missing a single duty is really not a big deal for your validator profitability. Unless you want to be at the top of the leaderboard, do not worry too much. You will be profitable again in no time once your validator is up next epoch.

Using the Prysm installation script

If you are running prysm.sh, all it takes to upgrade to the latest release is to stop your beacon node and validator (wait for the process to close down gracefully). Then, restart it with the same command you used to start the process. The script will automatically downloaded our latest release for you.

Using Docker

To update your Prysm with Docker, we recommend just pulling our :stable tag, which will always point to our latest release.

docker pull gcr.io/prysmaticlabs/prysm/beacon-chain:stabledocker pull gcr.io/prysmaticlabs/prysm/validator:stable

Using Bazel

To run our latest release with Bazel, you can look up our releases page, look at the commit hash of the latest release, then do git checkout COMMIT_HASH. Afterwards, you can re-run your beacon chain and validator as you ran them earlier with Bazel.

How to securely downgrade Prysm#

Sometimes, a new version might not work best for you and could impact your profitability negatively if there is an unforeseen issue in the software. To downgrade, there are a few important steps to keep in mind.

Downgrading between patch versions (v1.0.x)#

If you are downgrading between patch versions, which means only the last number in the version changed, such as v1.0.5 to v1.0.4, then follow the instructions below:

Using the Prysm installation script

If you are running prysm.sh, all it takes to downgrade to a previous release is to stop your beacon node and validator (wait for the process to close down gracefully).

Then, find the Prysm version you wish to run from our releases page, such as v1.0.5, then run the command export USE_PRYSM_VERSION=v1.0.5.

Then, restart it with the same command you used to start the process. The script will automatically use the release you specified.

Using Docker

To run a previous Prysm version with Docker, choose the release you want to run, then change all your docker run commands to use that version tag. For example, instead of docker run gcr.io/prysmaticlabs/prysm:stable, do docker run gcr.io/prysmaticlabs/prysm:v1.0.5 if you want to run version v1.0.5.

Using Bazel

To run our latest release with Bazel, you can look up our releases page, look at the release tag you want to run, such as v1.0.5, then do git checkout v1.0.5. Afterwards, you can re-run your beacon chain and validator as you ran them earlier with Bazel.

Using Systemd

Edit the systemd files for both validator (/etc/systemd/system/validator.service) and beacon (/etc/systemd/system/beacon.service). The filename depends on what you used when you installed, if you forgot the name, just ls that directory (/etc/systemd/system/) and edit them both. Add the Environment key under the [Service] group to have Environment = USE_PRYSM_VERSION=v2.0.2

Example for the beacon chain:

[Unit]Description     = Ethereum Beacon Chain ServiceWants           = network-online.targetAfter           = network-online.target
[Service]Type            = simpleUser            = ethExecStart       = /home/eth/prysm/prysm.sh beacon-chain --config-file=/etc/prysm/beacon-chain.yamlRestart         = on-failureTimeoutStopSec  = 900Environment     = USE_PRYSM_VERSION=v2.0.2
[Install]WantedBy    = multi-user.target

After you finish editing both of the files, you need to reload the service unit

sudo systemctl daemon-reload

Once you do that, the prysm beacon and validator are locked in that version, so you need to always update it. If you want to go back to the automatic upgrades after reboot, you just need to remove the Environment key.

Downgrading between minor versions (v1.x)#

If you are downgrading between minor versions, meaning the middle number in the version has changed, such as v1.1.0 to v1.0.x, then follow the instructions below carefully:

Using the Prysm installation script

If you are running prysm.sh, first stop your beacon node and validator (wait for the process to close down gracefully).

Next, we recommend backing up any important important folders such as your beacon node data directory and the validator wallet is important. You can simply make copies of the directories and keep them safe in case the downgrade process goes wrong.

Next up, run our database rollback command to make sure your database is going to be compatible with your new version. Find the folder where your validator.db file lives (it is in your wallet directory under a folder called direct or derived), then run:

prysm.sh validator db migrate down --datadir=/path/to/folder

Then, find the Prysm version you wish to run from our releases page, such as v1.0.5, then run the command set=USE_PRYSM_VERSION=v1.0.5.

Then, restart it with the same command you used to start the process. The script will automatically use the release you specified.

Using Docker

To run a previous Prysm version with Docker, choose the release you want to run, such as v1.0.5.

Next, we recommend backing up any important important folders such as your beacon node data directory and the validator wallet is important. You can simply make copies of the directories and keep them safe in case the downgrade process goes wrong.

Next up, run our database rollback command to make sure your database is going to be compatible with your new version. Find the folder where your validator.db file lives (it is in your wallet directory under a folder called direct or derived), then run:

docker run -v /path/to/folder:/data gcr.io/prysmaticlabs/prysm/validator:stable db migrate down --datadir=/data

Then change all your docker run commands to use that version tag. For example, instead of docker run gcr.io/prysmaticlabs/prysm:stable, do docker run gcr.io/prysmaticlabs/prysm:v1.0.5 if you want to run version v1.0.5.

Using Bazel

To run our latest release with Bazel, you can look up our releases page, look at the release tag you want to run, such as v1.0.5.

Next, we recommend backing up any important important folders such as your beacon node data directory and the validator wallet is important. You can simply make copies of the directories and keep them safe in case the downgrade process goes wrong.

Next up, run our database rollback command to make sure your database is going to be compatible with your new version. Find the folder where your validator.db file lives (it is in your wallet directory under a folder called direct or derived), then run:

bazel run //validator:validator -- db migrate down --datadir=/path/to/folder

Then do git checkout v1.0.5. Afterwards, you can re-run your beacon chain and validator as you ran them earlier with Bazel.

Downgrading between major version bumps#

For major version bumps such as from v1.0.0 to v2.0.0, you cannot downgrade as these are meant to be backwards incompatible changes.