Skip to main content

Snapshots

Beginner
Tutorial

Overview​

A canister contains compiled Wasm code and data, such as the canister ID, settings, and Wasm memory. If a canister stops working as expected, traps, or simply needs to be rolled back to a previous version, the developer can use canister snapshots. Developers can take a snapshot of a stopped canister to save the canister's current stable memory, heap memory, data, and Wasm module. This snapshot can be loaded at a later date, rolling the canister back to the code and data saved within that snapshot.

Canister snapshots are supported in dfx version 0.23.0 and newer.

Creating a snapshot​

To create a snapshot, first the canister must be stopped. Then, use the dfx canister snapshot create <canister-name> command:

dfx canister stop <canister-name>
dfx canister snapshot create <canister-name>
Output
Created a new snapshot of canister <canister-name>. Snapshot ID: 0000000000000000800000000010000a0101

Only a controller of a canister can take a snapshot or roll a canister back to a snapshot.

Currently, only one snapshot per canister can be saved. Taking another snapshot of a canister that already has a snapshot saved will overwrite the previous snapshot.

To take a snapshot of a canister on the mainnet, include the flag --network ic in the two commands shown above.

The snapshot ID can be used to load the snapshot at a later time. To list all snapshots saved for a canister, use the command dfx canister snapshot list <canister-name>:

dfx canister snapshot list <canister-name>
Output
0000000000000000800000000010000a0101: 2.39MiB, taken at 2024-09-16 19:40:23 UTC

Loading a snapshot​

To load a saved snapshot, first the canister must be stopped. Then, use the dfx canister snapshot load <canister-name> <snapshot-id> command:

dfx canister stop <canister-name>
dfx canister snapshot load <canister-name> <snapshot-id>

Loading a snapshot will replace the canister's current code and data with the snapshot code and data. Any new data that was added to the canister after the snapshot was taken will be deleted.

Deleting snapshots​

To delete a saved snapshot, use the command dfx canister snapshot delete <canister-name> <snapshot-id>

dfx canister snapshot delete <canister-name> <snapshot-id>

Common errors related to canister snapshots include:

Resources​