dfx start
Use the dfx start
command to start a local development environment and web server processes. This command must be run before you can deploy canisters to the local development environment and test your dapps during development.
By default, all local dfx
projects will use PocketIC to create this local development environment. You can run dfx start
and dfx stop
from any directory. See local server configuration and project-specific local networks below for exceptions.
Basic usage
dfx start [option] [flag]
Flags
You can use the following optional flags with the dfx start
command.
Flag | Description |
---|---|
--background | Starts the local development environment and web server processes in the background and waits for a reply before returning to the shell. |
--clean | Starts the local development environment and web server processes in a clean state by removing checkpoints from your project cache. You can use this flag to set your project cache to a new state when troubleshooting or debugging. |
--enable-bitcoin | Enables Bitcoin integration. |
--enable-canister-http | Deprecated and now enabled by default. |
--pocketic | Runs PocketIC instead of the replica. PocketIC is the default if no flag is used. |
Options
You can use the following option with the dfx start
command.
Option | Description |
---|---|
--host host | Specifies the host interface IP address and port number to bind the frontend to. The default for the local shared network is 127.0.0.1:4943 , while the default for a project-specific network is '127.0.0.1:8000'. |
--bitcoin-node host:port | Specifies the address of a bitcoind node. Implies --enable-bitcoin . |
--artificial-delay milliseconds | Specifies the delay that an update call should incur. Default: 600ms |
--domain domain | A domain that can be served. Can be specified more than once. These are used for canister resolution [default: localhost] |
Examples
You can start the local development environment and web server processes in the current shell by running the following command:
dfx start
If you start the local development environment in the current shell, you need to open a new terminal shell to run additional commands. Alternatively, you can start the local development environment in the background by running the following command:
dfx start --background
If you run the local development environment in the background, however, be sure to stop the local development environment before uninstalling or reinstalling the dfx
execution environment by running the following command:
dfx stop
You can view the current process identifier (pid
) for the local development environment process started by dfx
by running the following command:
more .dfx/pid
Local server configuration
The shared local network
dfx start
manages a PocketIC server that provides a local development environment. Running dfx deploy
and other commands will manage canisters on this local network in the same way that dfx deploy --network ic
deploys projects to the mainnet.
If run from outside a dfx
project directory, or if dfx.json
does not define the local
network, then dfx start
looks for the local
network definition in $HOME/.config/dfx/networks.json
. If this file does not exist or does not contain a definition for the local
network, then dfx
uses the following default definition:
{
"local": {
"bind": "127.0.0.1:4943",
"type": "ephemeral"
}
}
dfx
stores data for the shared local network in one of the following locations, depending on your operating system:
$HOME/.local/share/dfx/network/local
(Linux)$HOME/Library/Application Support/org.dfinity.dfx/network/local
(macOS)
Project-specific local networks
If dfx.json
defines the local
network, then dfx start
will use this definition and store network data files under <project dir>/.dfx/network/local
.
Note that for projects that define the local
network in dfx.json
, you can only run the dfx start
and dfx stop
commands 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.