Install
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. You can learn more about creating a canister in the creation documentation.
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 canister code
Code must be installed into the canister using the dfx canister install
command:
dfx canister install canister_name // install canister code locally
dfx canister install canister_name --network ic // install canister code on the mainnet
dfx canister install --all // install all canisters in the project's dfx.json file
Creating a canister on the mainnet will cost cycles
At this step, settings can be configured for the canister using the optional flags. View the full list of settings that can be configured.
Installing a gzip-compressed WebAssembly module
The size of programs that can be installed on ICP is currently limited to 2 MiB. WebAssembly modules that are (slightly) larger than 2 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 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
.
Troubleshooting
Failed to install Wasm module, no such file or directory.
If you receive an error such as:
Error: Failed to install wasm module to canister 'test'. Caused by: Failed to install wasm module to canister 'test'. Failed to read /home/gabriel/projects/motoko-test/.dfx/local/canisters/test/test.wasm. No such file or directory (os error 2)
You may need to run dfx build
, as this error indicates that the canister's Wasm module may not exist because it was not compiled. Learn more about how to compile a canister's Wasm module. Alternatively, you can run dfx deploy
, as it runs dfx build
and dfx install
as part of the deployment process.
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.