Installing the nRF Connect SDK

The recommended method to install the nRF Connect SDK is to use the nRF Connect for Visual Studio Code with the latest stable release of the nRF Connect SDK.

Complete the following steps:

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

  2. Install the latest version of Visual Studio Code for your operating system from the Visual Studio Code download page.

  3. Click the following button to install the latest version of nRF Connect for VS Code and the latest stable nRF Connect SDK release (v3.4.1):

    Install SDK in VS Code

    This installs the extension (if needed) and starts the installation of the nRF Connect SDK and toolchain v3.4.1.

    This installs the extension if you do not have it and then starts the installation of the nRF Connect SDK source code and the nRF Connect SDK toolchain. The whole process can take several minutes. You can follow the progress in the notification that appears in Visual Studio Code.

    The latest stable release is the latest release tag in the sdk-nrf repository that is not a release candidate (*-rc) or a preview tag (*-preview). For each version of the nRF Connect SDK, Nordic Semiconductor provides a dedicated nRF Connect SDK toolchain.

    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 development and release model, see the nRF Connect SDK code base and Release model pages, respectively.

    If you prefer, you can manually install the toolchain and the SDK in Visual Studio Code. Follow the steps in the extension get started guides. For a more guided installation approach, see the Installing nRF Connect SDK and VS Code exercise of the nRF Connect SDK Fundamentals course on Nordic Developer Academy.

    You can also install the extensions from the Open VSX Registry to editors based on Visual Studio Code and compatible with the VSIX format. However, Nordic Semiconductor does not test editors other than Visual Studio Code for compatibility with nRF Connect for VS Code. Any issues you encounter on other editors will not be prioritized.

After the installation, the extension’s Welcome View updates and shows the 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.

You now have everything that is required by Zephyr’s Getting Started Guide together with additional tools and Python dependencies that the nRF Connect SDK uses.

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

Alternative method: Installing using command line

As an alternative to using the recommended nRF Connect for VS Code, you can also install the nRF Connect SDK using command line and nRF Util.

Complete the following steps:

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

  2. Install the following required software tools:

  3. Install the latest stable nRF Connect SDK code and toolchain by completing the following steps:

    The latest stable release is the latest release tag in the sdk-nrf repository that is not a release candidate (*-rc) or a preview tag (*-preview). For each version of the nRF Connect SDK, Nordic Semiconductor provides a dedicated nRF Connect SDK toolchain.

    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 development and release model, see the nRF Connect SDK code base and Release model pages, respectively.

    1. Open a terminal window.

    2. Remove the lock on the nRF Util installation to be able to install other nRF Util commands. See Locking nRF Util home directory in the tool documentation for more information.

    3. Run the following command to install the nRF Util’s sdk-manager command:

      nrfutil install sdk-manager

    4. Run the following command to list the available installations:

      nrfutil sdk-manager search

      The versions from this list correspond to the nRF Connect SDK versions and will be version in the following step.

    5. Run the following command to install the SDK and the toolchain for the SDK version of your choice:

      nrfutil sdk-manager install version

      For example:

      nrfutil sdk-manager install v3.4.1

      This example command installs both the SDK code and the toolchain for the nRF Connect SDK v3.4.1. When you first install the nRF Connect SDK, it is recommended to install the latest released versions of the SDK and the toolchain.

      Note

      If you plan to work with a specific branch, use the command for installing the latest nRF Connect SDK release (v3.4.1) to install the latest toolchain. Then, you must use the west init command, described later in this procedure, to get the code of the desired branch. This is because the sdk-manager command only supports installing specific release versions.

      The sdk-manager command installs the SDK by default at C:/ncs/ on Windows and at ~/ncs/ on Linux, and the toolchain in the toolchains subdirectory. You can modify the SDK installation location, as explained in the command documentation. On macOS, the command defaults to /opt/nordic/ncs/ and /opt/nordic/ncs/toolchains and no other locations are allowed. The ncs directory holds all nRF Connect SDK repositories.

      If you have received a custom URL or a toolchain bundle ID for installing the toolchain, you can use dedicated commands to provide it. See the following section for the commands.

      If you have received a custom URL for installing the toolchain, you can use the following commands to set it as default, replacing the respective parameters:

      nrfutil sdk-manager config toolchain-index add index-name custom_toolchain_URL
nrfutil sdk-manager config toolchain-index set index-name

      If you have received a custom bundle ID for installing a specific toolchain version, you can use the following commands to provide it, replacing the respective parameter:

      nrfutil sdk-manager toolchain install --toolchain-bundle-id custom_bundle_ID

      To learn more about sdk-manager commands, use the nrfutil sdk-manager --help command, or see the command documentation.

    6. Start the toolchain environment for your operating system using the following command pattern, with --ncs-version corresponding to the nRF Connect SDK version you have installed:

      nrfutil sdk-manager toolchain launch --ncs-version version --terminal

      For example:

      nrfutil sdk-manager toolchain launch --ncs-version v3.4.1 --terminal

      This example command starts the toolchain environment for the nRF Connect SDK v3.4.1.

      Note

      You can also use other options instead of --ncs-version. See the sdk-manager command documentation for more information.

    7. Determine the identifier of the revision of the nRF Connect SDK you want to work with. See nRF Connect SDK code base for information about the available revision identifiers. When you first install the nRF Connect SDK, it is recommended to install the latest released versions of the SDK and the toolchain.

    8. Initialize west with the revision of the nRF Connect SDK that you want to check out, replacing the required parameters:

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

      In this command:

      • The first nRFConnectSDK_revision identifies the revision of the nRF Connect SDK.

      • The second nRFConnectSDK_revision_workspace_dir is the name of the workspace directory that will be created by west.

        For this installation method, it should be the same as the nRFConnectSDK_revision.

      The command creates the nRFConnectSDK_revision subdirectory and checks out the given revision of the nRF Connect SDK inside it. For example:

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

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

      • 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 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 main

      This will clone the manifest repository sdk-nrf into nrf.

      Initializing west with a specific revision of the manifest file does not lock your repositories to this version. Checking out a different branch or tag in the sdk-nrf repository and running west update changes the version of the nRF Connect SDK that you work with.

      Note

      If you get an error message when running west, update west to the latest version. See Troubleshooting West in the Zephyr documentation for more information.

    9. Enter the nRFConnectSDK_revision subdirectory and run the following command to clone the project repositories:

      west update

      Depending on your connection, this might take some time.

    10. Export a Zephyr CMake package. This allows CMake to automatically load the boilerplate code required for building nRF Connect SDK applications:

      west zephyr-export

    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.4.1 release, enter the following command:

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

    • 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 the GN tool page for more information.