Snapshots
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 command:
dfx canister stop <canister-name>
dfx canister snapshot create <canister-name>
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 canister snapshot ID will be returned:
Created a new snapshot of canister hello_backend. Snapshot ID: 0000000000000000800000000010000a0101
This 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>
The snapshot ID, snapshot size, and timestamp of when the snapshot was taken will be returned:
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 command:
dfx canister stop <canister-name>
dfx canister snapshot load <canister-name> <snapshot-id>
To load a snapshot on the mainnet, include the flag --network ic in the two commands shown above.
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>
To delete a snapshot on the mainnet, include the flag --network ic in the command shown above.
Errors related to canister snapshots
Common errors related to canister snapshots include: