Installing the nRF Connect SDK

There are different ways to install the nRF Connect SDK, depending on your preferred development environment and the toolchain management tool:

  • Using Visual Studio Code and the nRF Connect for VS Code extension (recommended)

  • Using command line and nRF Util

Regardless of which way you choose, the following steps install the nRF Connect SDK source code and the nRF Connect SDK toolchain. This includes everything that is required by Zephyr’s Getting Started Guide together with additional tools and Python dependencies that the nRF Connect SDK uses.

Using Visual Studio Code and the nRF Connect for VS Code extension is also covered in the Installing nRF Connect SDK and VS Code exercise of the nRF Connect SDK Fundamentals course on Nordic Developer Academy.

Update operating system

Before you start setting up the toolchain, install available updates for your operating system. See Requirements for information on the supported operating systems.

Install prerequisites

Depending on your preferred development environment, install the required tools:

Install the nRF Connect SDK toolchain

The nRF Connect SDK toolchain includes the Zephyr SDK and then adds tools and modules required to build nRF Connect SDK samples and applications on top of it. These include the required tools, the Python dependencies, and the GN tool for creating Matter applications.

When you first install the nRF Connect SDK, it is recommended to install the latest released versions of the SDK and the toolchain.

Depending on your preferred development environment, complete the following steps:

  1. Open the nRF Connect extension in Visual Studio Code by clicking its icon in the Activity Bar.

  2. In the extension’s Welcome View, click on Install Toolchain.

  3. Select the toolchain version to install. The toolchain version should match the nRF Connect SDK version you are going to work with. If you have received a custom URL for installing the toolchain, you can provide it using the Change Toolchain Index button in the quick pick’s header. The toolchain installation starts in the background, as can be seen in the notification that appears.

When you install the toolchain for the first time, the installed version is automatically selected for your project.

After installing the toolchain, you can access the Install Toolchain option by clicking on Manage toolchains.

Get the nRF Connect SDK code

Every nRF Connect SDK release consists of a combination of Git repositories at different versions and revisions, managed together by West. The revision of each of those repositories is determined by the current revision of the main (or manifest) repository, sdk-nrf. Simply put, you can work with the following versions of the nRF Connect SDK:

nRF Connect SDK version

Required identifier of the revision

Where to find the identifier

Specific release (recommended)

Release tag (for example, v2.5.2)

Release notes of the release

Development tag

Development tag (for example, v1.9.2-dev1)

Changelog of the tag

Branch

Branch name (for example, main)

sdk-nrf repository

Note

Unless you are familiar with the development process, you should always work with a specific release of the nRF Connect SDK.

For more information about the repository and development model, see the nRF Connect SDK code base page.

To clone the nRF Connect SDK code, complete the following steps:

  1. Open the nRF Connect extension in Visual Studio Code by clicking its icon in the Activity Bar.

  2. In the extension’s Welcome View, click on Manage SDKs. The list of actions appears in the Visual Studio Code’s quick pick.

  3. Click Install SDK. The list of available SDK versions appears in the Visual Studio Code’s quick pick.

  4. Select the SDK version to install. When you first install the nRF Connect SDK, it is recommended to install the latest released versions of the SDK and the toolchain.

The SDK installation starts and it can take several minutes.

If you used the default locations, your directory structure now looks similar to this:

<home>/
├─── toolchains/
│  └─── <toolchain-installation>
└─── <west-workspace>/
   ├─── .west/
   ├─── bootloader/
   ├─── modules/
   ├─── nrf/
   ├─── nrfxlib/
   ├─── zephyr/
   └─── ...

In this simplified structure preview, <home> corresponds to ncs/ and <toolchain-installation> and <west-workspace> correspond to the version names you installed. There are also additional directories, and the structure might change over time, for example if you later change the state of development to a different revision. The full set of repositories and directories is defined in the manifest file (see the file in the repository).

Set up the command-line build environment

Note

This step is only required when working on command line with freestanding applications.

In addition to the steps mentioned above, if you want to build and program your application from the command line, you have to set up your command-line build environment by defining the required environment variables every time you open a new command-line or terminal window. See Important Build System Variables for more information about the various relevant environment variables.

Define the required environment variables as follows, depending on your operating system:

Navigate to the ncs directory and run the following command in a terminal window:

zephyr/zephyr-env.cmd

If you need to define additional environment variables, create the file %userprofile%\zephyrrc.cmd and add the variables there. This file is loaded automatically when you run the above command. See Zephyr documentation about using zephyrrc files for more information.

System-wide installation

System-wide installation is an alternative to the recommended installation methods using the nRF Connect for VS Code extension or nRF Util. It gives you more control over each of the required tools, but requires more familiarity with Zephyr and with each of the tools.

To install the nRF Connect SDK system-wide, complete the following steps:

  1. Follow steps 1 and 2 in Zephyr’s Getting Started Guide to update your operating system and install dependencies.

  2. Install west. Expand the section below to see the commands.

    Note

    It is easy to run into Python package incompatibilities when installing dependencies at a system or user level. This situation can happen, for example, if working on multiple Zephyr versions or other projects using Python on the same machine.

    For this reason, it is suggested to use Python virtual environments.

    1. Create a new virtual environment:

      cd %HOMEPATH%
      python -m venv ncs/.venv
      
    2. Activate the virtual environment:

      ncs\.venv\Scripts\activate.bat
      

      Once activated your shell will be prefixed with (.venv). The virtual environment can be deactivated at any time by running deactivate.

      Note

      Remember to activate the virtual environment every time you start working.

    3. Install west:

      pip3 install west
      
  3. Get the nRF Connect SDK code as described in Get the nRF Connect SDK code for the command line. (You can skip step 2.) When you first install the nRF Connect SDK, it is recommended to install the latest released version of the SDK.

  4. Install the Python dependencies. Expand the section below to see the commands.

    Note

    You might run into Python package incompatibilities when installing dependencies at a system or user level. For this reason, it is suggested to use Python virtual environments.

    1. Enter the following commands in a cmd.exe terminal window in the ncs folder:

      pip3 install -r zephyr/scripts/requirements.txt
      pip3 install -r nrf/scripts/requirements.txt
      pip3 install -r bootloader/mcuboot/scripts/requirements.txt
      
  5. Follow step 4 in Zephyr’s Getting Started Guide to install the Zephyr SDK.

  6. Depending on your preferred development environment:

    • If you want to work with Visual Studio Code, install the nRF Connect for VS Code extension (the default IDE for the nRF Connect SDK).

    • If you want to work from command line, Set up the command-line build environment.

  7. If you want to build Matter applications, additionally install the GN meta-build system. This system generates the Ninja files that the nRF Connect SDK uses for Matter. See GN tool for more information.

Legacy installation with Toolchain Manager

Important

Toolchain Manager installation is recommended for the nRF Connect SDK v1.9.x and earlier.

Toolchain Manager is a tool available from nRF Connect for Desktop, a cross-platform tool that provides different applications that simplify installing the nRF Connect SDK. Both the tool and the application are available for Windows, Linux, and macOS.

To install the toolchain and the SDK using the Toolchain Manager app, complete the following steps:

  1. Install Toolchain Manager:

    1. Download nRF Connect for Desktop for your operating system.

    2. Install and run the tool on your machine.

    3. In the APPS section, click Install next to Toolchain Manager.

    The app is installed on your machine, and the Install button changes to Open.

  2. Install the nRF Connect SDK source code:

    1. Open Toolchain Manager in nRF Connect for Desktop.

      The Toolchain Manager window

      The Toolchain Manager window

    2. Click SETTINGS in the navigation bar to specify where you want to install the nRF Connect SDK.

    3. In SDK ENVIRONMENTS, click the Install button next to the nRF Connect SDK version that you want to install. When you first install the nRF Connect SDK, it is recommended to install the latest released versions of the SDK and the toolchain.

      The nRF Connect SDK version of your choice is installed on your machine. The Install button changes to Open VS Code.

  3. Set up the preferred building method:

    To build on the nRF Connect for VS Code extension, complete the following steps:

    1. In Toolchain Manager, click the Open VS Code button.

      A notification appears with a list of missing extensions that you need to install, including those from the nRF Connect for Visual Studio Code extension pack.

    2. Click Install missing extensions.

    3. Once the extensions are installed, click Open VS Code button again.

    You can then follow the instructions in Creating application in the nRF Connect for VS Code extension.