Skip to main content

Developer environment

Overview​

To develop and deploy Motoko canister smart contracts, you will need a developer environment that contains the Motoko compiler and base library. It is recommended to use the IC SDK, which includes Motoko, along with dfx, a command-line tool used to create, build, and deploy canisters on ICP.

Developer environments come in several types and formats, making developing flexible and accessible.

Cloud environments​

Gitpod and GitHub Codespaces are browser-based development environments that can be used to build, test, and run Motoko smart contracts.

Here are some starter projects for online Motoko canister development:

Learn more about Gitpod and GitHub Codespaces for Motoko development.

Container environments​

Developers may want to setup a containerized environment for Motoko and other ICP-related development. Container environments are especially useful for Windows-based systems, since dfx is not natively supported on Windows.

Learn more about developer containers and Docker containers for Motoko development.

Motoko playground​

Motoko playground is a browser-based developer environment that allows for temporary deployment and testing of canister smart contracts. Motoko playground can also be utilized through the dfx deploy --playground command via the CLI.

Canisters deployed to the Motoko playground use borrowed resources from a canister pool and are limited to a deployment length of 20 minutes. Therefore, the playground is not recommended for long-term development.

Learn more about the Motoko playground.

Local developer environment​

Before you start developing Motoko, verify the following:

  • You have an internet connection and access to a shell terminal on your local macOS or Linux computer.

  • You have a command line interface (CLI) window open. This window is also referred to as the 'terminal' window.

  • You have downloaded and installed the IC SDK package as described in the installing the IC SDK page.

  • You have a code editor installed. The VS Code IDE (with the Motoko extension) is a popular choice.

  • You have downloaded and installed git.

  • Assure that all packages and tools above are updated to the latest release versions.

Motoko version​

The following table details which version of Motoko shipped with each major version of the IC SDK.

IC SDK versionMotoko version
0.20.00.11.1
0.19.00.11.1
0.18.00.11.0
0.17.00.10.4
0.16.00.10.4
0.15.00.9.7
0.14.00.8.7
0.13.00.7.6
0.12.00.7.3
0.11.00.6.29
0.10.00.6.26
0.9.00.6.20
0.8.00.6.5
0.7.00.6.1

You can find out which version of Motoko shipped with a version of the IC SDK through the following file:

https://github.com/dfinity/sdk/blob/<VERSION>/nix/sources.json#L144

Replace <VERSION> with the IC SDK release version, such as 0.14.2.

Custom developer environment​

Specifying a custom version of the compiler​

To specify a custom version of the Motoko compiler to be used with dfx, you can use the package manager mops or vessel.

For mops, use the following command to download a different version of the Motoko compiler (moc):

mops toolchain use moc 0.10.3

For vessel, set the following environment variable:

DFX_MOC_PATH="$(vessel bin)/moc" dfx deploy

Specifying a custom version of the base library​

To specify a custom version of the Motoko base library to be used with dfx, you can use the package manager mops with the following command:

mops add base@<VERSION> && mops install

For example, to use base library version 0.9.0, use the command:

mops add base@0.9.0 && mops install

Specifying a custom version of dfx​

To specify a custom version of dfx, you can use the dfxvm tool. To set a default dfx version to be used in your project, run the command:

$ dfxvm default 0.7.2
...
info: installed dfx 0.7.2
info: set default version to dfx 0.7.2

Pass flags to moc in dfx.json​

You can pass flags directly to moc by adding an args field in your Motoko canister's description in your project's dfx.json file:

Here is an example dfx.json canister configuration that uses args:

...
  "canisters": {
    "hello": {
      "type": "motoko",
      "main": "src/hello/main.mo",
      "args": "-v --incremental-gc"
    },
  }
...