Installing the SDK

You can download and install the latest version of the DFINITY Canister smart contract SDK, called dfx, by running the command below. The topics here provide additional information about installing, upgrading, and removing the SDK.

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

Install on Mac/Linux

To install dfx, run

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

tip

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.

Install on Windows

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

Installing WSL 2

Follow Microsoft's instructions for installing the Windows Subsystem for Linux. Make sure you are running Windows 10 (version 2004 or higher) or Windows 11.

Supported WSL Versions

Theoretically, WSL 1 and WSL 2 should both allow you to run dfx. However, we recommend WSL 2. WSL Comparison explains the differences between WSL1 and WSL 2.

Check your WSL version

Run the command wsl –list –verbose (wsl -l -v) to check the Linux distributions installed on your Windows machine. Below is an example output.

```
NAME STATE VERSION
* Ubuntu Running 2
```

<p>To learn more about the <code>wsl</code> command, check the <a
  href="https://docs.microsoft.com/en-us/windows/wsl/basic-commands">command reference for WSL</a>.</p>
<h3 id="upgrade-to-wsl-2">Upgrade from WSL 1</h3>
<p>If you have WSL 1 installed, follow the <a
  href="https://docs.microsoft.com/en-us/windows/wsl/install#upgrade-version-from-wsl-1-to-wsl-2">upgrade
  instructions</a> to upgrade to WSL 2. Basically you need to: </p>
<ul>
  <li>Install the <a
    href="https://docs.microsoft.com/en-us/windows/wsl/install-manual#step-4---download-the-linux-kernel-update-package">WSL
    2 Linux kernel update package</a>.
  </li>
  <li>Run the following command to set your Linux distributions to version 2. <code>wsl
    --set-version &lt;distribution name&gt; 2</code></li>
</ul>
<h2 id="running-linux">Running Linux</h2>
<p>After you have WSL installed, you can launch the Linux distributions by name.</p>
<p>For example <code>Ubuntu.exe</code> is the command to start the <code>Ubuntu</code> distribution from the command
  line.</p>
<h2 id="installing-dfx">Installing DFX</h2>
<p>Once you have WSL installed, you can install <code>dfx</code> by running

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

</p>
<h2 id="troubleshooting">Troubleshooting</h2>
<h3 id="node-js-is-not-properly-installed">Node.js is not properly installed</h3>
<p>WSL 2 has node.js <code>10.x.x</code> installed by default. But the latest <code>dfx</code> requires
  node.js <code>16.0.0</code> or higher.</p>
<h3 id="permission-denied-when-running-dfx-start-">Permission Denied when running <code>dfx start</code></h3>
<p>Projects created from <code>dfx</code> need to be on the Linux filesystem instead of the Windows filesystem.
  Usually <code>cd ~</code> or <code>cd $HOME</code> in the WSL terminal will bring you to the home directory, and
  creating projects in there should work.</p>
<h3 id="no-internet-access-on-wsl">No internet access on WSL</h3>
<p>If you don’t have internet access on WSL, for instance you cannot ping any server successfully, most likely the
  nameserver on WSL is set to an internal WSL proxy. You can check the <code>/etc/resolv.conf</code> file to see if
  it’s the case. If it’s true, please follow the below steps to set to a valid nameserver: <br/>
  <ul>
    <li>Create the <code>/etc/wsl.conf</code> file and add the below content to it, this will prevent WSL from
      regenerating the <code>/etc/resolv.conf</code> file after restarting.
    </li>

    ```
    [network]
    generateResolvConf = false
    ```

    <li>Modify the nameserver in the <code>/etc/resolv.conf</code> file to a valid one, for example the Google
      nameserver <code>8.8.8.8</code>. </li>
    <li>On Windows, restart WSL to let this fix take effect.</li>
    <code>wsl.exe --shutdown</code>
  </ul>
</p>

---

What gets installed

The 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 SDK and all of its components	~/.cache/dfinity/uninstall.sh
versions	Cache directory that contains a subdirectory for each version of the 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 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 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.

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 SDK or to simply install the latest version. If you want to install e.g. version 0.11.1 specifically, you would run this:

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

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.

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 sdk repo. The README contains the instructions how you can build it on your own.

Removing the software

When you install the 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://internetcomputer.org/install.sh)"