dfx.json configuration options
Every project created and deployed with dfx requires a dfx.json file to be present in the project's root directory. The dfx.json file configures the project's settings, such as the canisters in the project, their name, type, and source file, default project build settings, and other configuration parameters such as Wasm optimizations. This page will detail some of the most common configuration options. For a full list of the possible configuration settings in dfx.json, view the dfx.json schema.
Default dfx.json file
By default, when a project is created with dfx new <project-name> --type=Motoko --no-frontend, the default dfx.json generated for the project will contain the following:
{
"canisters": {
"<project-name>_backend": {
"main": "src/<project-name>_backend/main.mo",
"type": "motoko"
}
},
"defaults": {
"build": {
"args": "",
"packtool": ""
}
},
"output_env_file": ".env",
"version": 1
}
This configuration contains the following components:
canisters: Defines the canister names and settings for the project. In this default example, a single canister calledexample_backendis defined.main: The primary source code file for the canister that serves as the canister's entrypoint. By default, for Motoko canisters this file ismain.mo. For Rust canisters, the 'candid' keyword is used in place of themainkeyword to define the entrypoint of a canister.type: Defines the type of the canister. Supported types aremotoko,rust,assets,pullandcustom.
defaults: Default settings for the project's build.build: Build process configuration.args: Arguments for thepacktoolsetting.packtool: Configures a package management tool for your canister's dependencies. Examples includemopsandvesselfor Motoko.
output_env_file: Environment variables will be written to this file without overwriting any user-defined variables if the file already exists.version: Refers to the iteration version for thisdfx.jsonfile. By default, versions ofdfx.jsonstart atversion: 1.
Full list of configuration options
All possible dfx.json configuration options are listed below.
canisters
Description: A mapping between canister names and their respective configuration. Each key is the name of a canister, and the value is a configuration object describing how to build, deploy, or refer to that canister.
Types: Each canister must have a type field, which can motoko, rust, assets, custom, or pull. Depending on the chosen type, different fields are required or allowed.
Rust specific fields:
candid: Path of the canister's Candid interface declaration file.crate: Name of the Rust crate that compiles to the canister's Wasm. If left unspecified, defaults to the crate with the same name as the package.package: Name of the Rust package that compiles the canister's Wasm.
Asset canister specific fields:
build: Commands that are executed in order to produce the canister's assets. Expected to produce assets in one of the paths specified by the 'source' field. Optional if there is no build necessary or the assets can be built using the defaultnpm run buildcommand.source: Folders from which assets are uploaded.workspace: The workspace inpackage.jsonthat the canister is in, if it is not in the root workspace.*Example::
"canisters": {
"example_frontend": {
"dependencies": [
"example_backend"
],
"source": [
"src/example_frontend/dist"
],
"type": "assets",
"workspace": "example_frontend"
}
},
Custom canister specific fields:
build: Commands that are executed in order to produce this canister's Wasm module. Expected to produce the Wasm in the path specified by the 'wasm' field. No build commands are allowed if thewasmfield is a URL. These commands are executed in the root of the project.candid: Path to this canister's Candid interface declaration. A URL to a Candid file is also acceptable.wasm: Path to Wasm to be installed. URLs to a Wasm module are also acceptable. A canister that has a URL to a Wasm module can not also havebuildsteps.Example:
"canisters": {
"example_backend": {
"build": "npx azle example_backend",
"candid": "src/example_backend/example_backend.did",
"gzip": true,
"main": "src/example_backend/src/index.ts",
"type": "custom",
"wasm": ".azle/example_backend/example_backend.wasm"
}
}
Pull specific fields:
id: Principal of the canister on the mainnet.Example:
{
"canisters": {
"dapp": {
"type": "motoko",
"main": "src/main.mo",
"dependencies": [
"dep_b", "dep_c"
]
},
"dep_b": {
"type": "pull",
"id": "yhgn4-myaaa-aaaaa-aabta-cai"
},
"dep_c": {
"type": "pull",
"id": "yahli-baaaa-aaaaa-aabtq-cai"
}
}
}
Other fields applicable to all canister types include:
args(string | null): Additional arguments to be passed to the canister.declarations: Configuration for generated type declarations. Options include:bindings("js","ts","did","mo"): Which languages’ declarations to generate. Default includes"js", "ts", "did".env_override(string | null): A string that replaces the default environment variable references in generated JavaScript.node_compatibility(boolean): Iftrue, enables Node-friendly defaults.output(string | null): Where to store the generated declarations. Defaults tosrc/declarations/<canister_name>.Example:
{
"declarations": {
"bindings": ["ts", "did"],
"node_compatibility": true,
"output": "src/declarations/my_canister"
}
}
dependencies(string[]): A list of canister names the canister depends on.gzip(boolean | null): Whether to gzip the built Wasm before installation (default:false).init_arg(string | null): Candid initialization argument as a string literal.init_arg_file(string | null): A file containing the initialization argument in Candid format.initialization_values: Defines initial resource settings on canister creation:compute_allocation(0–100): Percentage of max compute power guaranteed to be allocated for the canister.freezing_threshold(string | null): Denotes time duration in seconds, indicating the minimum duration that the canister should exist without running out of cycles. The default value of the freezing threshold is 2_592_000 (approximately 30 days).log_visibility: Defines access control for the canister's logs. Can be"public","controllers", or an object with"allowed_viewers": ["<principal>", ...].memory_allocation(Byte): Max memory (in bytes) for the canister. Can be integer or string with units (i.e.72, "2KB", or "4 MiB").reserved_cycles_limit(uint128 | null): Upper limit of reserved cycles. Reserved cycles are cycles that the system sets aside for future use by the canister. If a subnet's storage exceeds 450 GiB, then every time a canister allocates new storage bytes, the system sets aside some amount of cycles from the main balance of the canister. These reserved cycles will be used to cover future payments for the newly allocated bytes. The reserved cycles are not transferable and the amount of reserved cycles depends on how full the subnet is.\n\nA setting of 0 means that the canister will trap if it tries to allocate new storage while the subnet's memory usage exceeds 450 GiB.wasm_memory_limit(Byte | null): Specifies a soft limit (in bytes) on the Wasm memory usage of the canister.Update calls, timers, heartbeats, installs, and post-upgrades fail if the Wasm memory usage exceeds this limit. The main purpose of this setting is to protect against the case when the canister reaches the hard 4GiB limit. Must be a number of bytes between 0 and 2^48 (i.e. 256 TiB), inclusive. Can be specified as an integer, or as an SI unit string (e.g. "4KB", "2 MiB").wasm_memory_threshold(Byte | null): Specifies a threshold (in bytes) on the Wasm memory usage of the canister, as a distance fromwasm_memory_limit.When the remaining memory before the limit drops below this threshold, itson_low_wasm_memoryhook will be invoked. This enables it to self-optimize, or raise an alert, or otherwise attempt to prevent itself from reachingwasm_memory_limit.Must be a number of bytes between 0 and 2^48 (i.e. 256 TiB), inclusive. Can be specified as an integer, or as an SI unit string (e.g. \"4KB\", \"2 MiB\").Example:
{
"initialization_values": {
"compute_allocation": 50,
"memory_allocation": "2 MiB",
"log_visibility": "controllers"
}
}
main(string | null): Entry point for the canister's source code.metadata: Array of metadata sections that include:name(required): Name of the metadata section.content(string | null): Direct content of the section.path(string | null): Path to a file containing the section content. Conflicts withcontent. For sections with name=candid:service, this field is optional, and if not specified,dfxwill use the canister's Candid definition. If specified for a Motoko canister, the service defined in the specified path must be a valid subtype of the canister's actual Candid service definition.networks(string[] | null): Which networks this metadata applies to. Omit ornullfor all. If this field is absent, then it applies to all networks. An empty array means this element will not apply to any network.visibility:"public"or"private"."public": Anyone can query the metadata."private": Only controllers can query the metadata.Example:
{
"metadata": [
{
"name": "candid:service",
"path": "src/my_canister/my_canister.did",
"visibility": "public"
}
]
}
optimize: Configure the Wasm level optimization to be applied after the canister is built. Possible values arecyclesandsize. The valuecyclesoptimizes your canister at alevel 3inwasm-opt, which is the recommended default value.sizeprovides an aggressive optimization of the binary size. Learn more in thewasm-optdocumentation. Additional options include any of: "O4, O3, O2, O1, O0, Oz, Os". Disabled by default. If this option is specified, theshrinkoption will be ignored.post_install: Array or single string of commands run after the canister is installed. These commands are executed in the root of the project.pre_install: Array or single string of commands run before the canister is installed. These commands are executed in the root of the project.pullable: Configuration that allows external projects to pull this canister.wasm_url(required): URL to the canister's Wasm file.init_guide(required): Information regarding how consumers can initialize the canister.dependencies(required,string[]): Principal IDs of direct dependencies for this canister.init_arg(string | null): Default initialization argument(s) for the canister.wasm_hash(string | null): SHA256 hash of the Wasm module located atwasm_url. Only define this if the onchain canister Wasm is expected not to match the Wasm atwasm_url. The hash can also be specified via a URL using thewasm_hash_urlfield. If both are defined, thewasm_hash_urlfield will be ignored.wasm_hash_url(string | null): Specify the SHA256 hash of the Wasm module via this URL. Only define this if the onchain canister Wasm is expected not to match the Wasm atwasm_url. The hash can also be specified directly using thewasm_hashfield. If both are defined, thewasm_hash_urlfield will be ignored.Example:
{
"pullable": {
"wasm_url": "<https://example.com/path/to/my_canister.wasm>",
"init_guide": "Run with 'dfx canister install --argument <args>'",
"dependencies": ["abcde-aaaaa-aaaah-qwert-cai"],
"init_arg": "(record { example = \\"Hello\\" })"
}
}
remote: Configure this canister as remote on specified networks. On networks where this canister contains a remote ID, the canister is not deployed. Instead it is assumed to exist already under control of a different project.id(object): Maps a network name to a remote canister ID.candid(string | null): On networks where this canister is marked 'remote', this candid file is used instead of the one declared in the canister settings.
shrink(boolean | null): Whether to runic-wasm shrink. Enabled by default for Rust and Motoko canisters. Disabled by default for custom canisters.specified_id(string | null): Configure a static canister ID. This option only works with the local replica. If the--specified-idargument is also provided, thisspecified_idfield will be ignored.
Example:
{
"canisters": {
"asset_canister": {
"type": "assets",
"source": ["dist"],
"build": ["npm install", "npm run build"]
},
"motoko_canister": {
"type": "motoko",
"main": "src/motoko_canister/main.mo",
"declarations": {
"bindings": ["ts"],
"output": "src/declarations/motoko_canister"
}
}
}
}
defaults
Description: Default values for dfx start.
Types:
bitcoin: Configures a Bitcoin adapter.enabled(boolean): Enable or disable the Bitcoin adapter.log_level: Options are"critical","error","warning","info","debug", or"trace".canister_init_arg(string): Custom init arguments for the Bitcoin canister. Default:"(record { stability_threshold = 0 : nat; network = variant { regtest }; blocks_source = principal \"aaaaa-aa\"; fees = record { get_utxos_base = 0 : nat; get_utxos_cycles_per_ten_instructions = 0 : nat; get_utxos_maximum = 0 : nat; get_balance = 0 : nat; get_balance_maximum = 0 : nat; get_current_fee_percentiles = 0 : nat; get_current_fee_percentiles_maximum = 0 : nat; send_transaction_base = 0 : nat; send_transaction_per_byte = 0 : nat; }; syncing = variant { enabled }; api_access = variant { enabled }; disable_api_if_not_fully_synced = variant { enabled }})"nodes(string[] | null): Addresses of nodes to connect to in case discovery from seeds is not possible or sufficient.
bootstrap: Deprecated.build: Package manager configuration for the project.packtool(string | null): Configuration for the package manager. Options aremopsorvessel.args(string | null): Arguments for the package manager.
canister_http: Enable the HTTP adapter.enabled(boolean): Default:true.log_level: Options are"critical","error","warning","info","debug", or"trace".
proxy:domain: A list of domains that can be served. These are used for canister resolution. Default:localhost.
replica: Configuration for the local replica.log_level: Options are"critical","error","warning","info","debug", or"trace". Default:"error".port(uint16 | null): Local port for the replica. For the shared local network, the default is127.0.0.1:4943. For project-specific local networks, the default is127.0.0.1:8000.subnet_type: Determines the subnet type for the local replica. Affects things like cycles accounting, message size limits, cycle limits. Options are"system","application","verifiedapplication". Default:"application".Example:
{
"defaults": {
"replica": {
"log_level": "info",
"port": 4943,
"subnet_type": "application"
},
"canister_http": {
"enabled": true,
"log_level": "error"
}
}
}
dfx
Description: Statically sets the dfx version for the project.
Example:
{
"dfx": "0.25.1"
}
networks
Description: Define custom local networks. Learn more about custom network definitions and configurations.
Example:
{
"networks": {
"staging": {
"providers": ["icp0.app"],
"type": "persistent"
},
"local_custom": {
"type": "ephemeral",
"bind": "127.0.0.1:8000"
}
}
}
output_env_file
Description: Environment variables will be written to this file without overwriting any user-defined variables if the file already exists.
Example:
{
"output_env_file": ".env"
}
profile
Description: Sets the build profile (e.g., for Motoko or Rust canisters). A Debug build includes debug symbols and less optimization, while Release applies heavier optimizations.
Type: "Debug" or "Release"
Example:
{
"profile": "Release"
}
version
Description: Refers to the iteration version for this dfx.json file. By default, versions of dfx.json start at version: 1.
Example:
{
"version": 1
}
Further reading
There are several workflow-specific dfx.json configuration options detailed in the full dfx.json schema.