Installing manually

The recommended way to get started with the nRF Connect SDK is to install using nRF Connect for Desktop, which is described on the Installing automatically page. However, if you prefer to install the toolchain manually, follow the instructions described below.

To manually install the nRF Connect SDK, you must first install all the required tools and clone the nRF Connect SDK repositories.

The nRF Connect SDK toolchain includes the Zephyr SDK and then adds on top of it tools and modules required to build nRF Connect SDK samples and applications. If you already have your system set up to work with Zephyr OS, based on Zephyr’s Getting Started Guide, it means you have most of the requirements for the nRF Connect SDK installed. However, you still need to install a set of additional tools, including Python dependencies and the nRF Connect for VS Code extension (the default IDE for the nRF Connect SDK). You might also need the GN tool if you are interested in creating Matter applications.

Update your operating system

Before you start setting up the nRF Connect SDK toolchain, install available updates for your operating system. See Requirements for information on the supported operating systems and Zephyr features.

Install the required tools

The installation process is different depending on your operating system.

Note

You will be asked to reboot after installing some of the tools. You can skip these notifications and reboot only once after you complete the installation of all tools.

The recommended way of installing the required tools on Windows is to use Chocolatey, a package manager for Windows. Chocolatey installs the tools so that you can use them from a Windows command-line window.

To install the required tools, complete the following steps:

  1. Install chocolatey.

  2. Open a cmd.exe window as Administrator. To do so, press the Windows key, type “cmd.exe”, right-click the result, and choose Run as Administrator.

  3. Disable global confirmation to avoid having to confirm the installation of individual programs:

    choco feature enable -n allowGlobalConfirmation

  4. Use choco to install the required dependencies:

    choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
choco install ninja gperf python git dtc-msys2 wget 7zip

Ensure that these dependencies are installed with their versions as specified in the Required tools table. To check the list of installed packages and their versions, run the following command:

 choco list -lo

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.

To install the GN tool, complete the following steps:

  1. Download the latest version of the GN binary archive for Windows from the GN website.

  2. Extract the zip archive.

  3. Ensure that the GN tool is added to your PATH environment variable. For the exact instructions, see Environment Variables.

Install west

To manage the combination of repositories and versions, the nRF Connect SDK uses Zephyr’s west.

To install west, reopen the command prompt window as an administrator to ensure that Python is initialized, and complete the following step:

Enter the following command in a command-line window:

pip3 install west

Note

Ensure the west location is added to the path in environmental variables.

You only need to do this once.

Get the nRF Connect SDK code

Every nRF Connect SDK release consists of a combination of Git repositories at different revisions. The revision of each of those repositories is determined by the current revision of the main (or manifest) repository, sdk-nrf.

Note

The latest state of development is on the main branch of the sdk-nrf repository. To ensure a usable state, the sdk-nrf repository defines the compatible states of the other repositories. However, this state is not necessarily tested. For a higher degree of quality assurance, check out a tagged release.

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 development model section.

To clone the repositories, complete the following steps:

  1. Create a folder named ncs. This folder will hold all nRF Connect SDK repositories.

  2. Determine the identifier of the revision of the nRF Connect SDK you want to work with. The recommended way is to work with a specific release.

    • To work with a specific release, the identifier is the corresponding tag (for example, v2.4.0). You can find the tag in the Release notes of the release.

    • To work with a development tag, the identifier is the corresponding tag (for example, v1.2.99-dev1)

    • To work with a branch, the identifier is the branch name (for example, main to work with the latest state of development).

    • To work with a specific state, the identifier is the SHA (for example, 224bee9055d986fe2677149b8cbda0ff10650a6e).

  3. On the command line, go to the ncs folder (cd ncs) and initialize west with the revision of the nRF Connect SDK that you want to check out, replacing nRFConnectSDK_revision with the identifier:

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

    For example, to check out the v2.4.0 release, enter the following command:

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

    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.

    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.

    To check out the latest state of development, enter the following command:

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

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

  4. Enter the following command to clone the project repositories:

    west update

    Depending on your connection, this might take some time.

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

    west zephyr-export

Your directory structure now looks similar to this:

ncs
 |___ .west
 |___ bootloader
 |___ modules
 |___ nrf
 |___ nrfxlib
 |___ zephyr
 |___ ...

This is a simplified structure preview. There are additional folders, and the structure might change over time. The full set of repositories and folders is defined in the manifest file.

Install additional Python dependencies

The nRF Connect SDK requires additional Python packages to be installed.

Use the following commands to install the requirements for each repository.

Enter the following command in a command-line 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

Install the Zephyr SDK

The Zephyr Software Development Kit (SDK) contains toolchains for each of Zephyr’s supported architectures. Each toolchain provides a compiler, assembler, linker, and some, but not all, of the rest of the programs required to build Zephyr applications. The Zephyr SDK also includes additional host tools, such as custom QEMU and OpenOCD builds. It is at the base of the nRF Connect SDK toolchain, which adds on top of it several tools and modules of its own.

Note

When updating the Zephyr SDK, verify the Zephyr SDK variables. Make sure that the zephyr toolchain is selected, not gnuarmemb.

  1. Open a cmd.exe window by pressing the Windows key typing “cmd.exe”.

  2. Download the latest Zephyr SDK bundle:

    cd %HOMEPATH%
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.0/zephyr-sdk-0.16.0_windows-x86_64.7z

  3. Extract the Zephyr SDK bundle archive:

    7z x zephyr-sdk-0.16.0_windows-x86_64.7z

    Note

    It is recommended to extract the Zephyr SDK bundle at one of the following locations:

    • %HOMEPATH%

    • %PROGRAMFILES%

    The Zephyr SDK bundle archive contains the zephyr-sdk-0.16.0 directory and, when extracted under %HOMEPATH%, the resulting installation path will be %HOMEPATH%\zephyr-sdk-0.16.0.

  4. Run the Zephyr SDK bundle setup script:

    cd zephyr-sdk-0.16.0
setup.cmd

    Note

    You only need to run the setup script once after extracting the Zephyr SDK bundle.

    You must rerun the setup script if you relocate the Zephyr SDK bundle directory after the initial setup.

Install nRF Connect for VS Code extension

To open and compile projects in the nRF Connect SDK, install and use the recommended nRF Connect for VS Code extension.

The nRF Connect for VS Code extension is a complete IDE for developing applications compatible with the nRF Connect SDK. This includes an interface to the compiler and linker, an RTOS-aware debugger, a seamless interface to the nRF Connect SDK, and a serial terminal. For installation and migration instructions, see How to install the extension. For other instructions related to the nRF Connect for VS Code extension, see the nRF Connect for Visual Studio Code documentation site.

Set up the command-line build environment

In addition to Visual Studio Code, you can also build and program your application from the command line. You have to set up your 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 folder and enter the following command: 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 Option 3: Using zephyrrc files for more information.

You must also make sure that nrfjprog (part of the nRF Command Line Tools) is installed and its path is added to the environment variables. The west command programs the development kit by using nrfjprog by default. For more information on nrfjprog, see Programming SoCs with nrfjprog.