Skip to main content

dfx build

Reference

Use the dfx build command to compile your program into a WebAssembly module that can be deployed on ICP. You can use this command to compile all of the canisters that are defined in the project’s dfx.json configuration file or compile only a specific canister.

The dfx build command looks for the source code to compile using the information you have configured under the canisters section in the dfx.json configuration file.

Note that you can only run this command from within the project directory structure. For example, if your project name is hello_world, your current working directory must be the hello_world top-level project directory or one of its subdirectories.

Basic usage

dfx build [flag] [option] [--all | canister_name]

Flags

You can use the following optional flags with the dfx build command.

FlagDescription
--checkBuilds canisters using a temporary, hard-coded, locally-defined canister ID for testing that the canister compiles without connecting to ICP.

Options

You can specify the following options for the dfx build command.

OptionDescription
--network <network>Specifies the network alias or URL you want to connect to. You can use this option to override the network specified in the dfx.json configuration file.
--output-env-fileWrites dfx environment variables to a provided path. Overrides the output_env_file configuration from dfx.json if passed.

Arguments

You can specify the following arguments for the dfx build command.

ArgumentDescription
--allBuilds all canisters configured in the project’s dfx.json file.
canister_nameSpecifies the name of the canister you want to build. If you are not using the --all option, you can continue to use dfx build or provide a canister name as an argument. The canister name must match at least one name that you have configured in the canisters section of the dfx.json configuration file for your project.

Examples

In this example, the hello_world_backend canister contains the main program code and the hello_world_frontend canister store frontend code and assets. If you want to keep the hello_world_frontend canister defined in the dfx.json file, but only build the backend program, you could run the following command:

dfx build hello_world_backend

Building a specific canister is useful when you have multiple canisters defined in the dfx.json file, but want to test and debug operations for canisters independently.

To test whether a canister compiles without connecting to the mainnet or the local development environment, you would run the following command:

dfx build --check

Management canister

If dfx detects that your Motoko project is importing the management canister (e.g. import Management "ic:aaaaa-aa";) it will automatically provide the Candid interface for the management canister during the build.