Skip to main content

Installing the IC SDK

Overview​

The IC SDK is a software development kit used for creating and managing canister smart contracts on the ICP blockchain. The IC SDK supports Motoko and Rust programming languages by default, but developers can use other languages as well.

Components of the IC SDK​

The IC SDK installation script installs several components in default locations on your local computer. The following table describes the development environment components that the installation script installs:

ComponentDescriptionDefault location
dfxCommand-line interface (CLI)/usr/local/bin/dfx
mocMotoko runtime compiler~/.cache/dfinity/versions/<VERSION>/moc
replicaInternet Computer local network binary~/.cache/dfinity/versions/<VERSION>/replica
uninstall.shScript to remove the SDK and all of its components~/.cache/dfinity/uninstall.sh
versionsCache directory that contains a subdirectory for each version of the SDK you install.~/.cache/dfinity/versions

IC SDK vs CDK vs dfx​

There are a few components worth expanding on:

  1. IC SDK: this is the SDK created by DFINITY for creating and managing canisters. This is just one SDK in the ICP community and a common entry point for developers.

  2. Canister Development Kit (CDK): a CDK is an adapter used by the IC SDK that provides a programming language with the features necessary to create and manage canisters. The IC SDK comes with a few CDKs already installed for you so you can use them in the language of your choice. For example, the IC SDK comes with the Rust CDK already installed. CDKs that are not installed but available for developers include the:

Since CDKs are components used by the SDK, some developers choose to use the CDK directly (without the IC SDK), but typically are used as part of the whole IC SDK.

  1. dfx: dfx is the command-line interface for the IC SDK. This is why many commands for the IC SDK start with the command "dfx .." such as dfx new or dfx stop.

Installing the IC SDK​

You can download and install the latest version of the IC SDK for creating and managing canister smart contracts by running the command below. The following topics provide additional information about installing, upgrading, and removing the IC SDK.

The IC SDK 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.

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 the SDK. Each versioned subdirectory contains the all of the directories and files required for a specific version of the SDK. 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 the SDK contains the Motoko base library modules that are compatible with that version of the SDK. Because the Motoko base library is evolving rapidly, you should only use the base modules that are packaged with the version of the SDK that you have installed.

Bootstrap directory​

The bootstrap directory contains web server code that is deprecated. Beginning with version 0.7.0, agents can call an HTTP middleware server instead of the bootstrap code. This change enables canisters to respond to HTTP requests directly and operate more like traditional web-based applications.

Upgrading to the latest version​

If a new version of the IC SDK is available for download after your initial installation, you should install the updated version at your earliest convenience to get the latest fixes and enhancements as soon as possible.

You can use the dfx upgrade command to compare the version you have currently installed against the latest version available for download. If a newer version of dfx is available, the dfx upgrade command automatically downloads and installs the latest version.

You don't need to uninstall the software before installing the new version. However, if you want to perform a clean installation rather than an upgrade, you can first uninstall the software as described in removing the software, then re-run the download and installation command.

For information about the features and fixes in the latest release, see the release notes.

Installing a specific version​

The install script looks for the environment variable DFX_VERSION to check if it is supposed to install a specific version of the IC SDK or to simply install the latest version. If you want to install e.g. version 0.11.1 specifically, you can run the command:

DFX_VERSION=0.11.1 sh -ci "$(curl -sSL https://internetcomputer.org/install.sh)"

Setting a default version​

If defined, the IC SDK 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.

To set a global default (that gets overwritten by project-specific settings from the project's dfx.json), run the install script with the desired version, even if it is already installed.

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 the IC SDK​

When you install the IC SDK, the installation script puts the required binary files in a local directory and creates a cache. You can remove the IC SDK 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)"