Skip to main content

Canister state

Beginner
Management

After you deploy a canister, it can begin receiving and processing requests from users and from other canisters. Canisters that are available to send requests and receive replies are considered to be in a Running state.

Although canisters are normally placed in the Running state by default, there are cases where you might want to temporarily or permanently stop a canister. For example, you might want to stop a canister before upgrading it. Stopping a canister helps to ensure proper handling of any messages that are in progress and need to either run to completion or be rolled back. You might also want to stop a canister to clear its message queue cleanly as a prerequisite to deleting the canister.

To modify the state of a canister:

  • dfx canister status <canister-name>: Check if the canister is Running, Stopping, or Stopped. This command also returns details about the canister's settings.

  • dfx canister stop <canister-name>: Stop the canister. The canister's status will change to Stopping if it has in-flight messages that must be addressed before it can be stopped.

  • dfx canister start <canister-name>: Start the canister. After a canister has been stopped with dfx canister stop, the only way to restart it is through dfx canister start. Other commands, such as dfx deploy, do not start the canister if it has been manually stopped.