Installing the nRF Connect SDK

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

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.

Note

Using Visual Studio Code and nRF Connect for VS Code 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 to make sure it supports the nRF Connect SDK firmware.

Operating System

x64

ARM64

Windows 11

Built and tested with Twister.

Not supported.

Linux - Ubuntu 24.04 LTS

Built and tested with Twister. Comprehensive testing with Nordic Semiconductor hardware.

Not supported.

macOS 26

Not supported.

Built and tested with Twister.

Install prerequisites

Depending on your preferred development environment, install the following software tools.

Additionally, install Visual Studio Code:

Note

You can also use a different IDE compatible with the VSIX format and install the extensions that are part of the nRF Connect for VS Code Extension Pack from the Open VSX Registry. However, Nordic Semiconductor does not test editors other than Visual Studio Code for compatibility with nRF Connect for VS Code. While you are encouraged to report any issues you encounter on DevZone, issues discovered in editors other than Visual Studio Code and not reproducible in Visual Studio Code will not be prioritized.

Install the nRF Connect SDK code and toolchain

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, v3.3.0)

Release notes of the release

Git tag

Development tag (for example, v2.8.0-rc1)

Changelog of the tag

Branch

Branch name (for example, main)

sdk-nrf repository

For each version of the nRF Connect SDK, Nordic Semiconductor provides a dedicated 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 SDK tools, the Python dependencies, and the GN tool for creating Matter applications. You can check the versions of the required tools and Python dependencies on the Requirements reference page.

Note

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

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

When you install nRF Connect SDK for the first time, you have neither the SDK code nor the toolchain installed. Depending on your preferred development environment, complete the following steps:

Note

If you prefer, you can now start VS Code walkthrough and install the toolchain and the SDK from there.

  1. Open the nRF Connect extension in Visual Studio Code by clicking its icon in the Activity Bar. The extension loads and the Welcome View appears with two buttons: Install SDK and Install Toolchain.

  2. Click on Install SDK.

  3. Select the region for download.

    You only need to select the region for downloads once. The selected region applies to all future SDK and toolchain downloads. You can later change it in the Visual Studio Code settings.

    The list of available SDK types appears.

  4. Select nRF Connect SDK. The list of available stable versions for the nRF Connect SDK appears in the Visual Studio Code’s quick pick, grouped into two categories:

    • Pre-packaged SDKs & Toolchains - Available on the Nordic Semiconductor server. The package downloads both the SDK and toolchain, but skips the toolchain if you have it already installed. Available mostly for stable releases and some Git tags. Recommended for faster and more reliable download and installation.

    • GitHub - Taken from the nRF Connect by Nordic Semiconductor GitHub organization. Available for stable releases, but also Git tags and branches.

  5. Select an nRF Connect SDK version to install from the Pre-packaged SDKs & Toolchains category. 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 and toolchain installation starts and it can take several minutes. You can follow the progress in the notification that appears.

After the installation is complete, the extension’s Welcome View is updated to feature Manage toolchains and Manage SDKs menus. You can use these menus to install other versions of the nRF Connect SDK and toolchain, either together or separately. See the extension documentation for more information.

With the default locations to install the SDK code (C:/ncs on Windows, ~/ncs/ on Linux, and /opt/nordic/ncs/ on macOS) and its toolchain (C:/ncs/toolchains on Windows, ~/ncs/toolchains/ on Linux, and the non-modifiable /opt/nordic/ncs/toolchains/ on macOS), your directory structure now looks similar to this:

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

In this simplified structure preview, <toolchain-installation> corresponds to the toolchain version (most commonly, a SHA) and <west-workspace> corresponds to the SDK version name. 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 Environment Variables in the Zephyr documentation for more information about the various relevant environment variables.

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

Complete the following steps:

  1. Navigate to the ncs directory.

  2. Open the directory for your nRF Connect SDK version.

  3. 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.

Alternative method: System-wide installation

System-wide installation is an alternative to the recommended installation methods using nRF Connect for VS Code 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 the steps in the following sections of 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. Enter the ncs directory you created when setting up the virtual environment:

    cd %HOMEPATH%/ncs

  4. Get the nRF Connect SDK code. When you first install the nRF Connect SDK, it is recommended to install the latest released version of the SDK. Run the following command, where nRFConnectSDK_revision is the revision of the nRF Connect SDK you want to get the code of:

    west init -m https://github.com/nrfconnect/sdk-nrf --mr *nRFConnectSDK_revision*

    The command initializes a west workspace in the ncs directory and checks out the given revision of the nRF Connect SDK sdk-nrf in the nrf subdirectory. For example:

    • Specific release: To check out the v3.3.0 release, enter the following command:

      west init -m https://github.com/nrfconnect/sdk-nrf --mr v3.3.0

    • Git tag: To check out the v2.8.0-rc1 tag, enter the following command:

      west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.8.0-rc1

    • Branch: To check out the main branch that includes the latest state of development, enter the following command:

      west init -m https://github.com/nrfconnect/sdk-nrf --mr main

      Alternatively, you can omit the --mr parameter, in which case west uses main as the default nRFConnectSDK_revision.

  5. In the ncs directory, run the following command to clone the project repositories:

    west update

  6. 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. In the ncs directory, enter the following commands in a cmd.exe terminal window:

      pip3 install -r zephyr/scripts/requirements.txt
pip3 install -r nrf/scripts/requirements.txt
pip3 install -r bootloader/mcuboot/scripts/requirements.txt

  7. Follow the steps in the “Install the Zephyr SDK” section in Zephyr’s Getting Started Guide to install the Zephyr SDK.

  8. Depending on your preferred development environment:

  9. 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.