This DFINITY Canister Software Development Kit (SDK) provides tools, sample code, and documentation to help you create programs to run on a locally-deployed Internet Computer network. This Quick Start assumes that you are installing the DFINITY Canister SDK for the first time.
To get started, let’s build and deploy a simple Hello application 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 application using the command-line or in an alert pop-up window if you access the application in a browser.
Before you download and install this release of the DFINITY Canister SDK, verify the following:
You have an internet connection and access to a shell terminal on your local macOS or Linux computer.
Currently, the DFINITY Canister SDK only runs on computers with a macOS or Linux operating system.
node.jsinstalled if you want to include the default template files for front-end development in your project.
You can download the latest version of the DFINITY Canister Software Development Kit (SDK) directly from within a terminal shell on your local computer.
To download and install:
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
Download and install the DFINITY Canister SDK package by running the following command:
sh -ci "$(curl -fsSL https://sdk.dfinity.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.
yand press Return to continue with the installation.
The command displays information about the components being installed on the local computer.
If the installation script runs without any errors, everything you need to start developing programs that run on the Internet Computer platform will be available on your local computer.
To verify the SDK is ready to use:
Open a terminal shell on your local computer, if you don’t already have one open.
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 similar to the following:
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.
If you are planning to write a program using Motoko and use Visual Studio Code (VSCode) as your editor, you can install the Motoko language client plug-in for VSCode. The Motoko plug-in provides syntax highlighting, type information, and auto-completion features.
To install the plug-in:
Download and install Visual Studio Code, if it not already installed on your local computer.
Click View, then select Extensions.
motokoin the Search field.
Select the Motoko language support published by DFINITY Foundation, then click Install.
Applications for the Internet Computer start as projects.
You create projects using the
dfx parent command and its subcommands.
Creating a new project with
dfx adds a default project directory structure to your development workspace with template files to get you started.
To create a new project for your first application:
Open a terminal shell on your local computer, if you don’t already have one open.
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.
Change to your project directory by running the following command:
Before you can build your first project, you need to connect to the Internet Computer network either running locally in your development environment or running remotely on a sub-network that you can access.
These instructions assume you are running the Internet Computer locally. If you are connecting to an external Internet Computer network, you can skip this section.
As a best practice, this step requires you to have two terminal shells open, so that you can start and see network operations in one terminal and manage your project in another.
To start the network locally:
Open a new second terminal window or tab on your local computer and navigate to your project directory.
For example, you can do either of the following if running Terminal on macOS:
Click Shell, then select New Tab to open a new terminal in your current working directory.
Click Shell and select New Window, then run
cd ~/ic-projects/helloin the new terminal if your
helloproject is in the
You should now have two terminals open with your project directory as your current working directory.
Start the Internet Computer network on your local 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.
Leave the terminal window that displays network operations open and switch your focus to the first terminal window where you created your new project.
You perform the remaining steps in the terminal that doesn’t display network operations.
After you connect to the Internet Computer network running locally in your development environment, you can register, build, and deploy your application locally.
If you are connecting to an external Internet Computer network, you will need to use the
--network option to deploy to that network.
For information about deploying on the Internet Computer running remotely, see Deploying on the Internet Computer.
To deploy your first application locally:
Check that you are still in the root directory for your project, if needed.
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.
Register, build, and deploy your first application by running the following command:
If you have access to the Internet Computer running remotely, you can deploy to the that network instead of deploying locally by specifying the
--networkoption and the network alias configured in the
dfx.jsonfile. For information about deploying on the Internet Computer running remotely, see Deploying on the Internet Computer.
dfx deploycommand output displays information about the operations it performs. For example, this step registers two network-specific identifiers—one for the
hellomain program and one for the
hello_assetsfront-end user interface—and installation information similar to the following:
Installing code for canister hello, with canister_id 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q Installing code for canister hello_assets, with canister_id cxeji-wacaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
If you created a project with a different name, however, your canister names will match your project name instead of
hellocanister and the predefined
greetfunction by running the following command:
dfx canister call hello greet everyone
This example uses the
dfx canister callcommand to pass "everyone" as an argument 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
Verify the command displays the return value of the
Now that you have verified that your application has been deployed and tested its operation using the command line, let’s verify that you can access the front-end pop-up window using your web browser.
Open a browser.
Navigate to the default address and port number
127.0.0.1:8000, then append
hello_assetsidentifier to the URL.
For example, the full URL should look similar to the following:
Navigating to this URL displays the prompt pop-up window. For example:
Type a greeting, then click OK to return the greeting.
Click OK to close the alert pop-up window.
After testing the application in the browser, you can stop the local Internet Computer network so that it doesn’t continue running in the background.
To stop the local network:
In the terminal that displays network operations, press Control-C to interrupt the local network process.
Stop the local Internet Computer network running on your local computer by running the following command:
This Quick Start touched on only a few key steps to introduce the basic workflow you follow to develop programs of your own. There are more detailed examples and tutorials for you to explore in the Tutorials section of the SDK Developer Tools and in the Motoko Programming Language Guide.