Install, upgrade, or remove software

As described in the Quick start, you can download and install the latest version of the DFINITY Canister SDK package by running a command in a terminal shell. The topics in this section provide additional information about installing, upgrading, and removing the DFINITY Canister SDK.

Install the latest directly from a terminal

To download and install from a terminal shell:

  1. Open a terminal shell on your local computer.

    For example, on macOS open the Applications folder, then open Utilities and double-click Terminal.

  2. Download and install the SDK package by running the following curl command:

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

Install a specific version from a terminal

If you want to install a specific version, for example, to test against a previous version, you can modify the installation command to include a version.

To download and install a specific version from a terminal shell:

  1. Open a terminal shell on your local computer.

  2. Set the DFX_VERSION environment variable to the version of the DFINITY Canister SDK package you want to install as a prefix to curl command.

    For example, to install version 0.6.7, you would run the following command:

    DFX_VERSION=0.6.7 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"

Reviewing the license agreement

The installation script prompts you to read and accept the DFINITY Canister SDK License Agreement before installing the dfx command-line interface executable and its dependencies on your local computer. You must type y and press Enter to continue with the installation.

After you accept the license agreement, the installation script displays information about the components being installed on the local computer.

What gets installed

The DFINITY Canister 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:

Component Description Default location

dfx

DFINITY execution command-line interface (CLI)

/usr/local/bin/dfx

moc

Motoko runtime compiler

~/.cache/dfinity/versions/<VERSION>/moc

replica

Internet Computer local network binary

~/.cache/dfinity/versions/<VERSION>/replica

uninstall.sh

Script to remove the DFINITY Canister SDK and all of its components

~/.cache/dfinity

versions

Cache directory that contains a subdirectory for each version of the DFINITY Canister SDK you install.

~/.cache/dfinity/versions

Core components in a versioned directory

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

total 338216
drwxr-xr-x  44 pubs  staff      1408 Jul 21 11:38 base
drwxr-xr-x  20 pubs  staff       640 Jul 21 11:38 bootstrap
drwxr-xr-x   3 pubs  staff        96 Jul 21 11:38 canisters
-r-x------   1 pubs  staff  73477088 Jul 21 11:38 dfx
-r-x------   1 pubs  staff   3550256 Dec 31  1969 didc
-r-x------   1 pubs  staff   5383604 Dec 31  1969 ic-starter
drwxr-xr-x   7 pubs  staff       224 Jul 21 11:38 js-user-library
-r-x------   1 pubs  staff  16619864 Dec 31  1969 mo-doc
-r-x------   1 pubs  staff  16370424 Dec 31  1969 mo-ide
-r-x------   1 pubs  staff     78981 Dec 31  1969 mo-rts.wasm
-r-x------   1 pubs  staff  15977344 Dec 31  1969 moc
-r-x------   1 pubs  staff  41694644 Dec 31  1969 replica

Motoko base directory

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

Bootstrap directory

The bootstrap directory in the versioned subdirectory of the DFINITY Canister SDK provides the HTML and JavaScript files that are served when you run dfx start and access the localhost using the local Internet Computer web server.

files to support local front-end development and the local web server.

Canisters directory

The canisters directory in the versioned subdirectory of the DFINITY Canister SDK contains prebuilt canisters that provide functionality for specific canister types. For example, the prebuilt assetstorage canister stores and retrieves assets for the canisters that have the type key set to assets in the project’s dfx.json configuration file.

JavaScript agent library

The js-user-library directory in the versioned subdirectory of the DFINITY Canister SDK provides files to support writing front-end code that uses JavaScript to communicate with the Internet Computer. In most cases, you should only use the JavaScript agent library files that are packaged with the version of the DFINITY Canister SDK that you have installed.

Upgrading to the latest version

If a new version of the DFINITY Canister 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.

Note that 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.

Removing the software

When you install the DFINITY Canister SDK, the installation script puts the required binary files in a local directory and creates a cache. You can remove the 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://sdk.dfinity.org/install.sh)"