Skip to main content

Installing tools

Beginner
Getting started
Tutorial

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:

Gitpod and GitHub Codespaces​

If you use GitHub Codespaces or Gitpod to deploy your project, installing these dependencies is not necessary.

Links to available Codespaces and Gitpod examples can be found in the hello world example.

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
```bash
sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
```

If you are using a machine running Apple silicon, you will need to have [Rosetta](https://support.apple.com/en-us/HT211861) 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.

Learn more about dfxvm.

Building from source​

If you would like to compile dfx by yourself, head over to the IC SDK repo. The README contains the instructions on 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​