Skip to main content

Upgrade

Beginner
Tutorial

Overview​

Unlike a canister reinstall that preserves the canister identifier but no state, a canister upgrade enables you to preserve the state of a deployed canister, and change the code.

For example, assume you have a dapp that manages professional profiles and social connections. If you want to add a new feature to the dapp, you need to be able to update the canister code without losing any of the previously-stored data. A canister upgrade enables you to update existing canister identifiers with program changes without losing the program state.

To preserve state when you are upgrading a canister written in Motoko, be sure to use the stable keyword to identify the variables you want to preserve. For more information about preserving variable state in Motoko, see stable variables and upgrade methods.

To upgrade a canister:

  • Step 1: Open a new terminal and navigate to your project directory.​

    Start dfx with the command dfx start --background.

  • Step 2: Verify you have canister identifiers for all of the canisters you want to upgrade.​

    Note that your canister code must identify the variables for which to maintain state by using the stable keyword in the variable declaration.

    For more information about declaring stable variables, see the Motoko documentation.

  • Step 3: Upgrade all of the canisters by running the following command:​

      dfx canister install --all --mode upgrade // Local
      dfx canister install --all --mode upgrade --network ic // Mainnet

Common errors related to canister upgrades include: