Canister Snapshots

Snapshots capture a canister’s full state — WASM module, WASM memory, stable memory, and chunk store. Use them to back up canister state, transfer state between canisters, or recover from failed upgrades.

When to Use Snapshots

• Pre-upgrade backup — Capture state before deploying a risky upgrade so you can roll back
• State transfer — Download a snapshot from one canister and upload it to another (required for canister migration)
• Disaster recovery — Restore a canister to a known-good state
• Offline inspection — Download canister state to examine it locally

Creating a Snapshot

Create a snapshot of a canister’s current state. The canister must be stopped first:

icp canister stop my-canister -e ic
icp canister snapshot create my-canister -e ic
icp canister start my-canister -e ic

This returns a snapshot ID (hex string) that you’ll use to reference this snapshot.

Listing Snapshots

View all snapshots for a canister:

icp canister snapshot list my-canister -e ic

Downloading a Snapshot

Download a snapshot to a local directory for backup or transfer:

icp canister snapshot download my-canister <snapshot-id> -o ./my-snapshot -e ic

The output directory will contain:

File	Description
metadata.json	Snapshot metadata (timestamps, sizes, chunk hashes)
wasm_module.bin	The canister’s WASM module
wasm_memory.bin	WASM heap memory
stable_memory.bin	Stable memory
wasm_chunk_store/	WASM chunk store files (one per chunk)

For large canisters, downloads may take time. If interrupted, resume with:

icp canister snapshot download my-canister <snapshot-id> -o ./my-snapshot --resume -e ic

Uploading a Snapshot

Upload a previously downloaded snapshot to a canister:

icp canister snapshot upload my-canister -i ./my-snapshot -e ic

This creates a new snapshot on the target canister from the local files.

To replace an existing snapshot instead of creating a new one:

icp canister snapshot upload my-canister -i ./my-snapshot --replace <snapshot-id> -e ic

Like downloads, interrupted uploads can be resumed:

icp canister snapshot upload my-canister -i ./my-snapshot --resume -e ic

Restoring from a Snapshot

Restore a canister to the state captured in a snapshot. The canister must be stopped before restoring:

icp canister stop my-canister -e ic
icp canister snapshot restore my-canister <snapshot-id> -e ic

This replaces the canister’s current WASM module, memory, and stable memory with the snapshot’s contents. Start the canister again after restoring:

icp canister start my-canister -e ic

Deleting Snapshots

Remove a snapshot you no longer need:

icp canister snapshot delete my-canister <snapshot-id> -e ic

Example: Pre-Upgrade Backup

A common workflow is to create a snapshot before deploying an upgrade, so you can roll back if something goes wrong:

# 1. Stop the canister and create a snapshot before upgrading
icp canister stop my-canister -e ic
icp canister snapshot create my-canister -e ic
# Note the snapshot ID from the output

# 2. Deploy the upgrade
icp deploy my-canister -e ic

# 3. Test the upgrade
icp canister call my-canister health_check -e ic

# 4a. If everything works, optionally clean up the snapshot
icp canister snapshot delete my-canister <snapshot-id> -e ic

# 4b. If something is wrong, stop the canister and restore the snapshot
icp canister stop my-canister -e ic
icp canister snapshot restore my-canister <snapshot-id> -e ic
icp canister start my-canister -e ic

Example: Transferring State Between Canisters

Download a snapshot from one canister and upload it to another. This workflow is essential for canister migration, where you transfer state to a target canister on a different subnet before migrating the canister ID:

# Download from source
icp canister stop my-canister -e ic
icp canister snapshot create my-canister -e ic
icp canister start my-canister -e ic
icp canister snapshot download my-canister <snapshot-id> -o ./state-backup -e ic

# Upload to target (by canister ID if not in your project)
icp canister snapshot upload <target-id> -i ./state-backup -n ic
icp canister snapshot restore <target-id> <new-snapshot-id> -n ic

All snapshot commands accept either canister names (with -e) or canister IDs (with -n).

Next Steps

• Canister Migration — Move canisters between subnets
• Deploying to Mainnet — Production deployment guide

Browse all documentation →