Skip to main content

Create

Beginner
Developing canisters

Before a canister can be deployed, it must be created and registered with ICP, either locally, on the playground, or on the mainnet. When a canister is initially created, it is empty and does not contain code or state; it only contains the canister settings, canister ID, cycles balance, and controllers. Then, the canister's source code must then be compiled into WebAssembly and installed into the canister.

Once you have a project that contains a dfx.json file defining a project's canisters, you can create one of those canisters using the dfx canister create command.

Canister creation is done automatically in the background of the dfx deploy command. However, there may be certain workflows where creating an empty canister is necessary.

Canisters are created with dfx canister create. They are initially empty and do not contain program code. The code must be compiled into Wasm and installed into the empty canister before it can be deployed.

Create your canisters from within the project's directory:

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

  • dfx canister create <canister-name> --network=playground: Create a canister on the playground. Creating a canister on the playground is free, but canisters are temporary and will be removed after 20 minutes.

  • dfx canister create <canister-name> --network=ic: Create a canister on the mainnet. Creating a canister on the mainnet will cost cycles.

  • dfx canister create --all --network=ic: Create all canisters in the project's dfx.json file on the mainnet.

Settings can be configured while creating a canister using optional flags. View the full list of settings.

When a canister is created, the following steps happen:

  • A canister ID is registered with the local replica or the mainnet for each canister in the project's dfx.json file.

  • The following canister components are created:

    • List of controllers.
    • Cycles balance.
    • Reserved cycles balance.
    • Canister status.
    • Resource reservations.

  • Each canister ID is returned in the command line.

Common errors related to canister creation include: