Skip to main content

Installing tools

Overview

When developing on ICP, there are two primary tools used: dfx, a CLI tool used to create, deploy, and manage canisters, and a canister development kit (CDK) which provides an environment for writing canister code in different programming languages while supporting ICP features.

Currently supported CDKs include:

Installing dfx

dfx is part of the IC SDK.

dfx is natively supported on Linux or macOS 12.* Monterey or later.

There is no native support for dfx on Windows. However, by installing the Windows Subsystem for Linux (WSL 2), you can run dfx on a Windows system as described below.

Not all features of dfx may be supported on WSL 2.

You can download and install the latest version of the dfx by running the command below:

To install the IC SDK, run
sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"

If you are using a machine running Apple silicon, you will need to have Rosetta installed. You can install Rosetta by running softwareupdate --install-rosetta in your terminal.

Core components in a versioned directory

The ~/.cache/dfinity/versions directory stores one or more versioned subdirectories of dfx. Each versioned subdirectory contains the all of the directories and files required for a specific version of dfx. For example, if you list the contents of the ~/.cache/dfinity/versions/0.9.3 directory you would see the following core components:

total 349192
drwxr-xr-x 17 pubs staff 544 Mar 15 11:55 .
drwxr-xr-x 4 pubs staff 128 Mar 25 14:36 ..
drwxr-xr-x 49 pubs staff 1568 Mar 15 11:55 base
drwxr-xr-x 20 pubs staff 640 Mar 15 11:55 bootstrap
-r-x------ 1 pubs staff 66253292 Mar 15 11:55 dfx
-r-x------ 1 pubs staff 10496256 Dec 31 1969 ic-ref
-r-x------ 1 pubs staff 5663644 Dec 31 1969 ic-starter
-r-x------ 1 pubs staff 9604 Dec 31 1969 libcharset.1.0.0.dylib
-r-x------ 1 pubs staff 38220 Dec 31 1969 libffi.7.dylib
-r-x------ 1 pubs staff 668300 Dec 31 1969 libgmp.10.dylib
-r-x------ 1 pubs staff 958248 Dec 31 1969 libiconv.2.4.0.dylib
-r-x------ 1 pubs staff 4200 Dec 31 1969 libiconv.dylib
-r-x------ 1 pubs staff 96900 Dec 31 1969 libz.1.2.11.dylib
-r-x------ 1 pubs staff 15417684 Dec 31 1969 mo-doc
-r-x------ 1 pubs staff 14634020 Dec 31 1969 mo-ide
-r-x------ 1 pubs staff 15111508 Dec 31 1969 moc
-r-x------ 1 pubs staff 49404128 Dec 31 1969 replica

Motoko base directory

The base directory in the versioned subdirectory of dfx contains the Motoko base library modules that are compatible with that version of dfx. Because the Motoko base library is evolving rapidly, you should only use the base modules that are packaged with the version of dfx that you have installed.

Using the dfx version manager

Alteratively, to upgrade or install a specific version of dfx the dfx version manager (dfxvm) can be used.

First, install dfxvm using the following curl command:

sh -ci "$(curl -fsSL https://raw.githubusercontent.com/dfinity/sdk/dfxvm-install-script/install.sh)"

Upon installation, you will be prompted to select which version of dfx you'd like to install. You can also pass the intended version using an environment variable, such as:

DFX_VERSION=0.15.1 sh -ci "$(curl -fsSL https://raw.githubusercontent.com/dfinity/sdk/dfxvm-install-script/install.sh)"

Installing a specific version

Once dfxvm is installed, you can install other specific versions of dfx using the command:

dfxvm install [VERSION_NUMBER]

For example, you can install 0.15.0 with the command:

dfxvm install 0.15.0

Uninstalling a specific version

To uninstall a version of dfx using dfxvm, use the command:

dfxvm uninstall [VERSION_NUMBER]

For example, to uninstall version 0.14.4, use the command:

dfxvm uninstall 0.14.4

Upgrading to the latest version

To update dfx to the latest version, use the command:

dfxvm update

Setting a default version

If defined, dfx will always run the version specified in the project's dfx.json in the key "dfx". For example, if your dfx.json contains "dfx": "0.11.1", any dfx command you run within this project's directory will be executed by dfx of version 0.11.1. Should the defined version not be installed (e.g. because you cloned a repo that was created for a different version than you have installed locally), dfx will report an error.

You can learn more about dfxvm here.

Building from source

If you would like to compile dfx by yourself, head over to the IC SDK repo. The README contains the instructions how you can build it on your own.

Uninstalling dfx

When you install dfx, the installation script puts the required binary files in a local directory and creates a cache. You can remove the dfx binaries and cache from your local computer by running the uninstall script located in the .cache folder.

For example:

~/.cache/dfinity/uninstall.sh

If you are uninstalling because you want to immediately reinstall a clean version of dfx, you can run the following command:

~/.cache/dfinity/uninstall.sh && sh -ci "$(curl -sSL https://internetcomputer.org/install.sh)"

Installing a CDK

Motoko

By default, Motoko is installed with dfx. Alternatively, you can build it from source following these instructions.

Rust

By default, the Rust CDK is installed with dfx. Alternatively, you can install it yourself by adding the following dependency in your Cargo.toml file:

[lib]
crate-type = ["cdylib"]

[dependencies]
ic-cdk = "0.12"
# Only necessary if you want to define Candid data types
candid = "0.10"

Below is a brief example on how to use the Rust CDK:

#[ic_cdk::query]
fn hello() -> String {
"world".to_string()
}

TypeScript / JavaScript

The TypeScript and JavaScript CDK, known as Azle, can be installed with dfx in versions v0.16.1 and newer. To install it manually, you can follow these steps.

Azle is currently in beta and should be used with caution.

Python

The Python CDK, known as Kybra, can be installed by following these steps:

  • Step 1: Install pyenv

curl https://pyenv.run | bash
  • Step 2: Install Python 3.10.7:

~/.pyenv/bin/pyenv install 3.10.7
  • Step 3: Install dfx v0.14.2:

DFX_VERSION=0.14.2 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
  • Step 4: Add $HOME/bin to your path:

echo 'export PATH="$PATH:$HOME/bin"' >> "$HOME/.bashrc"

Kybra is currently in beta and should be used with caution.

Solidity

Solidity smart contracts can be created using the Bitfinity EVM. To use the Bitfinity EVM, you can make calls to the Bitfinity mainnet or testnet..

Learn more about how to use the Bitfinity EVM

Bitfinity EVM is currently in beta and should be used with caution.

C++

C++ is supported through the ICPP-pro CDK, which can be installed with the following steps:

  • Step 1: Install icpp-pro with pip:

pip install icpp-pro
  • Step 2: Install wasi-sdk:

icpp install-wasi-sdk
  • Step 3: Install the latest version of dfx:

sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"

Next steps