This scenario assumes that you are installing the IC SDK for the first time and want to run a canister in a local canister execution environment instead of deploying it to the Internet Computer blockchain.
To get started, let’s build and deploy a simple 'Hello, world!' canister that has just one function—called
greet function accepts one text argument and returns the result with a greeting similar to Hello, everyone! in a terminal if you run the canister using the command-line or in an HTML page if you access the canister in a browser.
Before you download and install this release of the IC SDK, verify the following:
You have an internet connection and access to a shell terminal on your local computer.
node.jsinstalled if you want to include the default template files for frontend development in your project.
Download and install
You can download the latest version of the IC SDK directly from within a terminal shell on your local computer.
These instructions are for macOS or Linux machines. For Windows instructions, please see here.
To download and install:
Step 1: Open a terminal shell on your local computer.
For example, open Applications > Utilities, then double-click Terminal or press ⌘+spacebar to open Search, then type
Step 2: Download and install the IC SDK package by running the following command:
sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
This command prompts you to read and accept the license agreement before installing the DFINITY execution command-line interface (CLI) and its dependencies on your local computer.
Step 3: Type
yand press Return to continue with the installation.
This command displays information about the components being installed on the local computer.
Verify the IC SDK is ready to use
If the installation script runs without any errors, everything you need to start developing programs that run on the IC will be available on your local computer.
To verify the IC SDK is ready to use:
Step 1: Open a terminal shell on your local computer, if you don’t already have one open.
Step 2: Check that you have the DFINITY execution command-line interface (CLI) installed and the
dfxexecutable is available in your PATH by running the following command:
The command displays version information for the
dfxcommand-line executable. You can see the latest version in the release notes.
Step 3: Preview usage information for the other
dfxcommand-line sub-commands by running the following command:
The command displays usage information for the
dfxparent command and its subcommands.
Create a new project
Dapps on the Internet Computer start as projects. You create projects using the
dfx parent command and its subcommands.
For this guide, you’ll start with the default sample dapp to illustrate creating dapp using the starter files in a project. When you create a new project, the
dfx command-line interface adds a default project directory structure to your workspace. The previous guide covers the template files that make up a project directory in the explore the default project page.
To create a new project for your first application:
Step 1: Open a terminal shell on your local computer, if you don’t already have one open.
Step 2: Create a new project named
helloby running the following command:
dfx new hello
dfx new hellocommand creates a new
helloproject directory, template files, and a new
helloGit repository for your project.
If you use a different project name instead of
hello, make note of the name you used. You’ll need to use that project name in place of the
helloproject name throughout these instructions.
Step 3: Change to your project directory by running the following command:
Start the local deployment
Before you can build your first project, you need to connect to the local canister execution environment. As a best practice, this step requires you to have two terminal shells open, so that you can start and see canister execution operations in one terminal and manage your project in another.
To prepare the local canister execution environment:
Step 1: Open a new second terminal window or tab on your local computer.
Step 2: Navigate to the root directory for your project, if necessary.
You should now have two terminals open with your project directory as your current working directory in both terminals.
Step 3: Start the local canister execution environment on your computer in your second terminal by running the following command:
Depending on your platform and local security settings, you might see a warning displayed. If you are prompted to allow or deny incoming network connections, click Allow.
Step 4: Leave the terminal window that displays canister execution operations open and switch your focus to the first terminal window where you created your new project.
You should perform the remaining steps in the terminal that doesn’t display canister execution operations.
Register, build, and deploy the application
After you connect to the local canister execution environment you can register, build, and deploy your dapp locally.
To deploy your first dapp locally:
Step 1: Check that you are still in the root directory for your project, if needed.
Step 2: Ensure that
nodemodules are available in your project directory, if needed, by running the following command:
For more information about this step, see ensuring node is available in a project.
Step 3: Register, build, and deploy your first dapp by running the following command:
dfx deploycommand output displays information about the operations it performs. For example, this step registers two identifiers. One is for the
hello_backendmain program and the other one for the
hello_frontendfrontend user interface and installation information similar to the following:
Creating a wallet canister on the local network.
The wallet canister on the "local" network for user "mainnet" is "rwlgt-iiaaa-aaaaa-aaaaa-cai"
Deploying all canisters.
Creating canister hello_backend...
hello_backend canister created with canister id: rrkah-fqaaa-aaaaa-aaaaq-cai
Creating canister hello_frontend...
hello_frontend canister created with canister id: ryjl3-tyaaa-aaaaa-aaaba-cai
Creating UI canister on the local network.
The UI canister on the "local" network is "r7inp-6aaaa-aaaaa-aaabq-cai"
Installing code for canister hello_backend, with canister ID rrkah-fqaaa-aaaaa-aaaaq-cai
Installing code for canister hello_frontend, with canister ID ryjl3-tyaaa-aaaaa-aaaba-cai
Uploading assets to asset canister...
Staging contents of new and changed assets:
/sample-asset.txt 1/1 (24 bytes)
/logo2.svg 1/1 (15139 bytes)
/index.js.map 1/1 (681670 bytes)
/index.js.map (gzip) 1/1 (156940 bytes)
/favicon.ico 1/1 (15406 bytes)
/main.css 1/1 (537 bytes)
/main.css (gzip) 1/1 (297 bytes)
/index.html 1/1 (690 bytes)
/index.html (gzip) 1/1 (386 bytes)
/index.js (gzip) 1/1 (152884 bytes)
/index.js 1/1 (637230 bytes)
Frontend canister via browser
Backend canister via Candid interface:
If you created a project with a different name, however, your canister names will match your project name instead of
You should also note that the first time you deploy,
defaultidentity and a local cycle wallet controlled by your
defaultidentity. A cycles wallet is a special type of canister that enables you to transfer cycles to other canisters.
To deploy this sample dapp locally, you don’t need to know anything about your default developer identity, using a cycles wallet, or managing cycles. We’ll cover these topics later; for now, just note that these are created for you automatically.
Step 4: Call the
hello_backendcanister and the predefined
greetfunction by running the following command:
dfx canister call hello_backend greet everyone
Let’s take a closer look at this example command:
dfx canister callcommand requires you to specify a canister name and a method—or function—to call.
hello_backendspecifies the name of the canister you want to call.
greetspecifies the name of the function you want to call in the
everyoneis the text data type argument that you want to pass to the
Remember, however, that if you created a project with a different name, the canister name will match your project name and you’ll need to modify the command line to match the name you used instead of
hello_backend. If you were to choose
testas the projects name, your backend canister would be called
test_backendand the frontend canister
Step 5: Verify the command displays the return value of the
Test the dapp frontend
Now that you have verified that your dapp has been deployed and tested its operation using the command line, let’s verify that you can access the frontend using your web browser.
Step 1: Open a browser.
Step 2: Navigate to the URL output by the
dfx deploycommand in the previous step.
Use the URL after
Frontend canister via browser; in our case that's
Navigating to this URL displays a basic HTML page with a sample asset image file, an input field, and a button. For example:
Step 3: Type a greeting, then click Click Me button to return the greeting.
Stop the local canister execution environment
After testing the application in the browser, you can stop the local canister execution environment so that it doesn’t continue running in the background.
To stop the local deployment:
Step 1: In the terminal that displays the development server, press Control-C to interrupt the development server process.
Step 2: In the terminal that displays canister execution operations, press Control-C to interrupt the local network process.
Step 3: Stop the local canister execution environment running on your local computer by running the following command:
This guide touched on only a few key steps to introduce the basic workflow for developing dapps of your own. You can find more detailed examples and guides to help you learn about how to use Motoko and how to develop dapps to run on the Internet Computer blockchain throughout the documentation.
Here are some suggestions for where to go next:
Building on the IC to explore sample dapps.
Concepts to learn about different IC concepts and services.
Convert ICP tokens to cycles if you have ICP tokens that you want to convert to cycles to enable you to deploy dapp to the Internet Computer blockchain.
IC glossary to learn the definitions of various terms used within the IC.
On-chain deployment if you have cycles and are ready to deploy an application to the Internet Computer blockchain mainnet.
What is Candid? to learn how the Candid interface description language enables service interoperability and composability.