Installing manually
The recommended way to get started with the nRF Connect SDK is to use nRF Connect for Desktop. See the Installing automatically page for information about how to install automatically.
Note
If you use nRF Connect for Desktop to install the nRF Connect SDK, you can skip this section of the documentation. If you prefer to install the toolchain manually, see the following documentation for instructions.
To manually install the nRF Connect SDK, you must install all required tools and clone the nRF Connect SDK repositories. See the following sections for detailed instructions.
If you already have your system set up to work with Zephyr OS based on Zephyr’s Getting Started Guide, you already have some of the requirements for the nRF Connect SDK installed. The only requirement not covered by the installation steps in Zephyr is the GN tool. This tool is needed only for Matter applications.
Before you start setting up the 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 for 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:
Open a
cmd.exewindow as Administrator. To do so, press the Windows key, type “cmd.exe”, right-click the result, and choose Run as Administrator.Disable global confirmation to avoid having to confirm the installation of individual programs:
choco feature enable -n allowGlobalConfirmationUse
chocoto install the required dependencies:choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System' choco install ninja gperf python git dtc-msys2 wget unzip
Ensure that these dependencies are installed with their versions as specified in the Required tools table.
To install the required tools on Ubuntu, complete the following steps:
Download, inspect and execute the Kitware archive script to add the Kitware APT repository to your sources list. A detailed explanation of
kitware-archive.shcan be found here kitware third-party apt repository:wget https://apt.kitware.com/kitware-archive.sh sudo bash kitware-archive.sh
Use
aptto install the required dependencies:sudo apt install --no-install-recommends git cmake ninja-build gperf \ ccache dfu-util device-tree-compiler wget \ python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1
Verify the versions of the main dependencies installed on your system by entering:
cmake --version python3 --version dtc --version
Ensure that these dependencies are installed with their versions as specified in the Required tools table. Refer to the Install Linux Host Dependencies page for additional information on updating the dependencies manually. If you are using other Linux-based operating systems, see the Install Requirements and Dependencies section in the Zephyr documentation.
To install the required tools, complete the following steps:
Install Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Use
brewto install the required dependencies:brew install cmake ninja gperf python3 ccache qemu dtc wget libmagic
Ensure that these dependencies are installed with their versions as specified in the Required tools table. Also see macOS alternative setup instructions in the Zephyr documentation for additional information.
In addition to these required tools, install the GN meta-build system if you are interested in building Matter applications. This system generates the Ninja files that the nRF Connect SDK uses.
To install the GN tool, complete the following steps:
Download the latest version of the GN binary archive for Windows from the GN website.
Extract the
ziparchive.Check that the GN tool is added to your
PATHenvironment variable. See Environment Variables for instructions if needed.
To install the GN tool, complete the following steps:
Create the directory for the GN tool:
mkdir ${HOME}/gn && cd ${HOME}/gnDownload the GN binary archive and extract it by using the following commands:
wget -O gn.zip https://chrome-infra-packages.appspot.com/dl/gn/gn/linux-amd64/+/latest unzip gn.zip rm gn.zip
The wget tool is installed when installing the required tools on Linux.
Add the location of the GN tool to the system
PATH. For example, if you are usingbash, run the following commands:echo 'export PATH=${HOME}/gn:"$PATH"' >> ${HOME}/.bashrc source ${HOME}/.bashrc
To install the GN tool, complete the following steps:
Create the directory for the GN tool:
mkdir ${HOME}/gn && cd ${HOME}/gnInstall the wget tool:
brew install wget
Download the GN binary archive and extract it by using the following commands:
For 64-bit ARM (M1 and M2) host architecture:
wget -O gn.zip https://chrome-infra-packages.appspot.com/dl/gn/gn/mac-arm64/+/latest unzip gn.zip rm gn.zip
For 64-bit AMD (Intel) host architecture:
wget -O gn.zip https://chrome-infra-packages.appspot.com/dl/gn/gn/mac-amd64/+/latest unzip gn.zip rm gn.zip
Add the location of the GN tool to the system
PATH. For example, if you are usingbash, run the following commands:Create the
.bash_profilefile if you do not have it already:touch ${HOME}/.bash_profileAdd the location of the GN tool to
.bash_profile:echo 'export PATH=${HOME}/gn:"$PATH"' >> ${HOME}/.bash_profile source ${HOME}/.bash_profile
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 to ensure that Python is initialized and complete the following step:
Enter the following command in a command-line window:
pip3 install west
Enter the following command in a terminal window:
pip3 install --user west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
Enter the following command in a terminal window:
pip3 install west
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:
Create a folder named
ncs. This folder will hold all nRF Connect SDK repositories.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.1.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,
mainto work with the latest state of development).To work with a specific state, the identifier is the SHA (for example,
224bee9055d986fe2677149b8cbda0ff10650a6e).
From the command line, initialize west with the revision of the nRF Connect SDK that you want to check out, replacing NCS_revision with the identifier:
west init -m https://github.com/nrfconnect/sdk-nrf --mr NCS_revision
For example, to check out the v2.1.0 release, enter the following command:
west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.1.0
To check out the latest state of development, enter the following command:
west init -m https://github.com/nrfconnect/sdk-nrf --mr main
Note
If you get an error message when running west, update west to the latest version. See Troubleshooting West if you need 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 updatechanges the version of the nRF Connect SDK that you work with.This will clone the manifest repository sdk-nrf into
nrf.Enter the following command to clone the project repositories:
west update
Depending on your connection, this might take some time.
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
|___ ...
Note that there are additional folders, and that the structure might change. 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
Enter the following command in a terminal window in the ncs folder:
pip3 install --user -r zephyr/scripts/requirements.txt pip3 install --user -r nrf/scripts/requirements.txt pip3 install --user -r bootloader/mcuboot/scripts/requirements.txt
Enter the following command in a 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
Install a Toolchain
A toolchain provides a compiler, assembler, linker, and other programs required to build Zephyr applications.
The Zephyr Software Development Kit (SDK) contains toolchains for each of Zephyr’s supported architectures. It also includes additional host tools, such as custom QEMU and OpenOCD builds.
Note
When updating Zephyr SDK, verify the Zephyr SDK variables.
Make sure that the zephyr toolchain is selected, not gnuarmemb.
Open a command-line window.
Download and verify a Zephyr SDK bundle:
cd %HOMEPATH% wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.1/zephyr-sdk-0.14.1_windows-x86_64.zip
Extract the Zephyr SDK bundle archive:
unzip zephyr-sdk-0.14.1_windows-x86_64.zipNote
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.14.1directory and, when extracted under%HOMEPATH%, the resulting installation path will be%HOMEPATH%\zephyr-sdk-0.14.1.Run the Zephyr SDK bundle setup script:
cd zephyr-sdk-0.14.1 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.
Open a terminal window.
Download and verify a Zephyr SDK bundle:
cd ~ wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.1/zephyr-sdk-0.14.1_linux-x86_64.tar.gz wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.1/sha256.sum | shasum --check --ignore-missing
If your host architecture is 64-bit ARM (for example, Raspberry Pi), replace
x86_64withaarch64in order to download the 64-bit ARM Linux SDK.Extract the Zephyr SDK bundle archive:
tar xvf zephyr-sdk-0.14.1_linux-x86_64.tar.gz
Note
It is recommended to extract the Zephyr SDK bundle at one of the following locations:
$HOME$HOME/.local$HOME/.local/opt$HOME/bin/opt/usr/local
The Zephyr SDK bundle archive contains the
zephyr-sdk-0.14.1directory and, when extracted under$HOME, the resulting installation path will be$HOME/zephyr-sdk-0.14.1.Run the Zephyr SDK bundle setup script:
cd zephyr-sdk-0.14.1 ./setup.shNote
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 udev rules, which allow you to flash most Zephyr boards as a regular user:
sudo cp ~/zephyr-sdk-0.14.1/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d sudo udevadm control --reload
Open a terminal window.
Download and verify a Zephyr SDK bundle:
For 64-bit ARM (M1 and M2) host architecture:
cd ~ wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.1/zephyr-sdk-0.14.1_macos-aarch64.tar.gz wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.1/sha256.sum | shasum --check --ignore-missing
For 64-bit AMD (Intel) host architecture:
cd ~ wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.1/zephyr-sdk-0.14.1_macos-x86_64.tar.gz wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.1/sha256.sum | shasum --check --ignore-missing
Extract the Zephyr SDK bundle archive, matching the file name of the bundle you downloaded:
tar xvf zephyr-sdk-0.14.1_macos-x86_64.tar.gz
Note
It is recommended to extract the Zephyr SDK bundle at one of the following locations:
$HOME$HOME/.local$HOME/.local/opt$HOME/bin/opt/usr/local
The Zephyr SDK bundle archive contains the
zephyr-sdk-0.14.1directory and, when extracted under$HOME, the resulting installation path will be$HOME/zephyr-sdk-0.14.1.Run the Zephyr SDK bundle setup script:
cd zephyr-sdk-0.14.1 ./setup.shNote
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
You can install the nRF Connect for VS Code extension to open and compile projects in the nRF Connect SDK.
The nRF Connect for VS Code extension is a complete IDE for developing applications for nRF91, nRF53 and nRF52 Series devices. 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 detailed instructions, see the nRF Connect for Visual Studio Code documentation site.
Note
If you are building the application or sample using SEGGER Embedded Studio IDE or on the command line and want to migrate to Visual Studio Code, follow the instructions in the migrating from other IDEs to VS Code documentation.
For instructions specifically for installing, see Installing using Visual Studio Code.
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.
Navigate to the ncs folder and enter the following command: source zephyr/zephyr-env.sh
If you need to define additional environment variables, create the file ~/.zephyrrc 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.
Navigate to the ncs folder and enter the following command: source zephyr/zephyr-env.sh
If you need to define additional environment variables, create the file ~/.zephyrrc 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.