ICP Developer Guide Chapter 1: Setting Up Your Internet Computer Development Environment

Introduction

In the previous article, you learned the fundamental concepts of the Internet Computer Protocol (ICP), a third-generation blockchain designed to power decentralized applications that can run entirely on-chain. ICP acts like a decentralized cloud, enabling developers to build and deploy applications without relying completely on centralized hosting providers.

You might ask: how is this possible? The answer is that ICP applications run inside canister smart contracts. A canister can store data, run code, serve web content and interact with users through normal web browsers. This means a developer can build a web application where the backend and frontend are hosted on the Internet Computer network.

            Goal of this chapter: Prepare your computer and accounts so that you are ready to create,
            test and deploy your first Internet Computer application.
          

Prerequisites

Before you start coding on the Internet Computer, you need a suitable operating system, command-line tools, a code editor, Node.js and the ICP development tools.

Requirement	Recommended Setup
Operating System	Windows 10/11 with WSL2, macOS, or Ubuntu Linux.
Windows Users	Use WSL2 with Ubuntu and run development commands inside the Linux terminal.
Node.js	Use the current LTS version. Official ICP quickstart now recommends Node.js LTS v22+.
Code Editor	Visual Studio Code is recommended for beginners.
GitHub Account	Useful for version control and storing sample projects.
Programming Basics	Basic knowledge of HTML, CSS, JavaScript and command-line usage.
ICP Developer Tools	Use the modern `icp-cli` workflow, or the legacy `dfx` workflow if following older tutorials.

Updated note: The original article used Node.js v20 and dfx. The official ICP quickstart now shows Node.js LTS v22+ and the newer icp-cli tooling. This page keeps the useful dfx identity commands while also showing the newer quickstart path.

Installing ICP Development Tools

Option A: Modern ICP CLI Quickstart

The official quickstart installs icp-cli and ic-wasm using npm. This is now the recommended beginner path in the current ICP developer documentation.

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

For Motoko projects, install the Motoko package manager:

npm install -g ic-mops

Verify the installation:

icp --version
ic-wasm --version

Creating a Quick Hello World Project

The current ICP quickstart can create a full-stack hello-world project with a Motoko backend and React frontend:

icp new hello-icp --subfolder hello-world --silent
cd hello-icp

Start the local Internet Computer network:

icp network start -d

Deploy the project locally:

icp deploy

Call the backend canister from the terminal:

icp canister call backend greet '("World")'

Stop the local network when finished:

icp network stop

Option B: Legacy IC SDK / dfx Installation

Many existing ICP tutorials still use the dfx command-line tool. If you are following the original article or older Internet Computer examples, you may see this installation command:

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

After installation, check your installed version:

dfx --version

Apple Silicon note: Some older toolchains may require Rosetta on Apple Silicon. If your Mac reports a compatibility problem, install Rosetta using softwareupdate --install-rosetta.

Creating an ICP Identity

On the Internet Computer, an identity is based on a cryptographic key pair. The identity controls your principal ID, which represents you when you interact with canisters. This is different from a normal username and password account.

To create a new identity with dfx, use:

dfx identity new <identity_name>

Example:

dfx identity new MyDeveloperIdentity

Identity names should be easy to remember. Avoid using spaces. You can create multiple identities for different development projects.

Very important: Back up your 24-word seed phrase securely. If you lose the seed phrase and the local identity file, you may lose access to that identity. Never publish your seed phrase online.

Principal ID

A principal ID is the identifier used by ICP canisters to recognize a user, canister or other entity. After creating an identity, select it:

dfx identity use <identity_name>

Then get your principal ID:

dfx identity get-principal

A principal ID may look like this:

zxyfn-yljyi-bn6dy-ixi7n-jez74-nk723-pvj3m-jykes-dhqon-3ktql-uae

            Think of it this way: Your principal ID is like your blockchain identity inside the Internet
            Computer ecosystem. Canisters use it to identify who is calling a function or interacting with the app.
          

Ledger Account ID

Your ledger account ID is used to receive ICP tokens in the ICP ledger. It is different from your principal ID, although it is derived from your identity.

To display your ledger account ID:

dfx identity use <identity_name>
dfx ledger account-id

A ledger account ID may look like this:

1370f0ea74b35f33d2a2fee64a7a8c53cd52d6dd82c1cdfe08712dcd863692ab

Identifier	Purpose
Principal ID	Identifies a user, canister or system identity when interacting with ICP applications.
Ledger Account ID	Used to receive and hold ICP token balances in the ICP ledger.

Importing an Existing Identity

If you change your computer or want to use the same identity in a new development environment, you can import an identity from a seed phrase file.

dfx identity import --seed-file <seedfile.txt> <identity_name>

The seed file should contain the seed phrase for the identity. Store it only in a secure location and delete temporary copies after importing.

Security reminder: Do not store a seed phrase in a public GitHub repository, cloud note app, public folder or shared computer. Anyone with the seed phrase can control the identity.

Checking ICP Token Balance

To check the ICP token balance of your ledger account on the ICP main network, use:

dfx ledger --network ic balance

The --network ic parameter connects to the ICP main network. Without this parameter, many commands may use your local development network instead.

Local vs main network: Local development uses a local replica on your computer. Mainnet deployment uses the live Internet Computer network and requires real cycles.

Internet Identity

Internet Identity is the built-in authentication system for Internet Computer applications. It allows users to log in using device credentials such as passkeys, biometrics or hardware security keys. The system is designed to avoid exposing a single persistent identity across all apps.

Open the Internet Identity portal: Go to https://identity.ic0.app/.
Create a new identity: Click the option to create a new Internet Identity.
Register a device: Use your device passkey, biometric authentication, security key or QR-based flow.
Save your identity number: Record your Internet Identity number in a safe place.
Add recovery methods: Add a second device or recovery method to avoid being locked out.

            Why Internet Identity matters: It makes Web3 login feel more like modern web login, while
            still supporting decentralized applications on ICP.
          

Plug Wallet

Plug Wallet is a popular wallet used in the ICP ecosystem. It can store ICP tokens and interact with supported Internet Computer applications. It is available as a browser extension and mobile app.

You can learn more from the official Plug Wallet website: https://plugwallet.ooo/

Tool	Main Use
Internet Identity	Login and authentication for ICP applications.
NNS Dapp	ICP governance, staking, neurons and accounts.
Plug Wallet	Wallet for ICP ecosystem assets and supported dApp interactions.
dfx / icp-cli	Developer tools for creating, deploying and managing canisters.

Network Nervous System

The Network Nervous System, or NNS, is the on-chain governance system that manages the Internet Computer network. ICP token holders can stake ICP into neurons and participate in proposal voting. The NNS can manage network upgrades, node providers, economic parameters and system canisters.

You can access the NNS dapp here: https://nns.ic0.app/

Key Functions of the NNS

1. Governance

ICP holders can vote on proposals related to protocol upgrades, economics, node providers and network configuration.

2. Token Economics

The NNS manages important ICP token economics and supports the conversion of ICP into cycles for computation.

3. Node Management

The NNS oversees network configuration and the addition, removal or configuration of node machines and subnets.

4. Network Upgrades

ICP can be upgraded through governance proposals without relying on traditional hard-fork coordination.

Developer perspective: You do not need to fully master NNS governance before building your first app, but you should understand that ICP is governed on-chain and upgraded through proposals.

Suggested Beginner Workflow

If you are new to ICP development, follow this simple workflow before moving to more advanced topics.

Install prerequisites: Prepare WSL2, macOS or Ubuntu, Node.js LTS, VS Code and Git.
Install ICP tools: Use icp-cli for the current quickstart, or install dfx if following older tutorial commands.
Create a test project: Build and deploy a hello-world app locally before trying mainnet.
Create a developer identity: Use dfx identity new and back up the seed phrase.
Learn the identifiers: Understand the difference between principal ID and ledger account ID.
Create Internet Identity: Use Internet Identity for app login and NNS access.
Explore NNS and Plug Wallet: Understand wallet, accounts, staking and governance basics.
Move to Chapter 2: Start building your first real ICP application with canisters.

Common Beginner Problems and Fixes

Problem	Possible Cause	Suggested Fix
Command not found	Tool was not installed globally or terminal was not restarted.	Check installation, restart terminal and verify with `icp --version` or `dfx --version`.
Windows command fails	Commands are run in PowerShell instead of WSL Ubuntu.	Open Ubuntu through WSL and run ICP development commands there.
Node.js version error	Node.js version is too old.	Install the current LTS version recommended by the official ICP quickstart.
Cannot access local frontend	Local network is not running or deployment failed.	Run `icp network start -d` and redeploy with `icp deploy`.
Identity lost	Local identity file deleted and seed phrase not backed up.	Restore from the seed phrase if available. If not, the identity may be unrecoverable.
Mainnet deployment fails	No real cycles available for canister creation and operation.	Acquire ICP, convert to cycles, or use the official cycle management workflow.

Conclusion

This chapter prepared your development environment for building on the Internet Computer. You learned the required tools, how to install ICP development utilities, how to create and manage identities, how to obtain a principal ID and ledger account ID, and how Internet Identity, Plug Wallet and the Network Nervous System fit into the ICP ecosystem.

The most important beginner habit is to separate local experimentation from mainnet deployment. Build locally first, understand your identity and canister workflow, then move to the live Internet Computer network when you are ready.

In the next chapter, you can start building and deploying your first real canister-based ICP application.

References and Further Reading

About the Author

Dr. Liew Voon Kiong is an author, educator and blockchain advisor. He writes practical guides on blockchain, Web3, fintech, artificial intelligence and digital transformation for students, developers, professionals and business readers.