Skip to content

installation.md

Latest commit

 

History

History
170 lines (113 loc) · 5.21 KB

installation.md

File metadata and controls

170 lines (113 loc) · 5.21 KB
title description
Installation
Install icp-cli, ic-wasm, and language toolchains on macOS, Linux, or Windows via npm, Homebrew, or shell script.

Set up everything you need to build and deploy canisters on the Internet Computer.

What you'll install:

Tool Purpose
icp-cli Core CLI for building and deploying canisters
ic-wasm Optimizes WebAssembly for the Internet Computer
Language toolchain Motoko compiler (via mops) or Rust compiler

Windows users: Local networks require Docker Desktop, and Motoko requires WSL. For the full experience, install both and run commands inside WSL. Rust-only projects deploying to mainnet can run natively on Windows.

Linux users: The pre-compiled binary requires system libraries that may be missing on minimal installs. If installation fails or icp won't start, install these dependencies:

# Ubuntu/Debian
sudo apt-get install -y libdbus-1-3 libssl3 ca-certificates
# Fedora/RHEL
sudo dnf install -y dbus-libs openssl ca-certificates

Quick Install via npm (Recommended)

Required: Node.js (LTS) — needed for npm and for building frontend canisters.

1. Install the core tools:

npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm

2. Install your language toolchain:

Motoko:

npm install -g ic-mops

Rust (if not already installed):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-unknown-unknown

3. Verify installation:

icp --version
ic-wasm --version

Alternative Installation Methods

If you prefer not to use npm, or need platform-specific options, see the sections below.

icp-cli

Homebrew (macOS/Linux):

brew install icp-cli

Shell Script (macOS/Linux/WSL):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.sh | sh

Shell Script (Windows):

powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.ps1 | iex"

ic-wasm

ic-wasm is a WebAssembly post-processing tool that optimizes canisters for the Internet Computer. It provides:

  • Optimization: ~10% cycle reduction for Motoko, ~4% for Rust
  • Size reduction: ~16% smaller binaries for both languages
  • Metadata: Embed Candid interfaces and version information
  • Shrinking: Remove unused code and debug symbols

When is it needed?

  • Required if using official templates (motoko, rust, hello-world) — all backend templates use recipes that depend on ic-wasm
  • Required if using official recipes (@dfinity/motoko, @dfinity/rust) — these recipes inject required metadata using ic-wasm
  • Not required if building canisters with custom script steps that don't invoke ic-wasm

Installation:

Homebrew (macOS/Linux):

brew install ic-wasm

Shell Script (macOS/Linux):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/ic-wasm/releases/latest/download/ic-wasm-installer.sh | sh

Shell Script (Windows):

powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/ic-wasm/releases/latest/download/ic-wasm-installer.ps1 | iex"

Learn more: ic-wasm repository

Language Toolchains

Motoko:

curl -fsSL cli.mops.one/install.sh | sh

Note: Requires Node.js and a package manager (npm, pnpm, or bun). The shell script installs the latest Mops version stored onchain on ICP.

Rust:

Install from rustup.rs:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-unknown-unknown

Troubleshooting

"command not found: icp" (after curl install)

The binary isn't in your PATH. Add this to your shell config (~/.bashrc, ~/.zshrc, etc.):

export PATH="$HOME/.cargo/bin:$PATH"

Then restart your shell or run source ~/.bashrc (or ~/.zshrc).

"Cannot connect to Docker" (Windows)

On Windows, Docker Desktop must be running before starting a local network. Ensure:

Network launcher download fails

The network launcher downloads automatically on first use. If it fails:

  • Check your internet connection
  • Try again (transient failures are possible)
  • Download manually from icp-cli-network-launcher releases and set ICP_CLI_NETWORK_LAUNCHER_PATH

Next Steps

Browse all documentation →