Install

Beginner

Tutorial

Overview

When a canister has been initially created, it is empty and does not contain code or state. It only contains information such as the settings, canister ID, cycles balance, and controllers. Learn more about creating a canister.

Canister code must be compiled into Wasm. Then, the Wasm module can be installed into the empty canister.

Installing canister code

Prerequisites

Install the IC SDK.

Write a smart contract.

Create your canister.

Compile your canister code into Wasm.

Code must be installed into a canister using the dfx canister install command from the project's directory:

• dfx canister install <canister-name>: Install canister code locally. The local replica must be running to create a canister locally. Start it with dfx start --background.

• dfx canister install <canister-name> --network=playground: Install canister code on the playground. Installing code in a canister on the playground is free, but canisters are temporary and will be removed after 20 minutes.

• dfx canister install <canister-name> --network=ic: Install canister code on the mainnet. Installing code in a canister on the mainnet will cost cycles.

• dfx canister install --all --network=ic: Install code for all canisters in the project's dfx.json file on the mainnet.

When a canister's code is installed, the following components are created:

• The canister's code in the form of a canister module.

• The canister's state, including the canister's memory and global values.

• Additional IC-specific information, such as the canister's input and output queues.

Installing a gzip-compressed WebAssembly module

The size of programs that can be installed on ICP is currently limited to 10 MiB. WebAssembly modules that are (slightly) larger than 10 MiB can still be installed on ICP by using gzip file compression before uploading. ICP will then decompress the file and install the contained WebAssembly module.

The WebAssembly module is compressed using gzip and then uploaded by dfx canister install, you may need to add --mode reinstall or --mode upgrade when uploading the module to an existing canister.

gzip my-canister.wasm
dfx canister install my-canister --wasm my-canister.wasm.gz

Compression is currently not supported by dfx deploy.

Errors related to Wasm modules

Common errors related to installation and Wasm modules include:

• Install code rate limited.
• Canister not empty.
• Wasm module not found.
• Wasm module too large.
• Wasm module duplicate exports.
• Wasm module exports too many methods.
• Wasm module sum of exported name lengths too large.
• Wasm module too many functions.
• Wasm module too many globals.
• Wasm module function complexity too high.
• Wasm module function too large.
• Wasm module code section too large.