Extension configuration overview - nRF Connect for VS Code
Skip to content

Extension configuration overview

When you start working with the extension, you only need to set up the SDK and toolchain versions. The nRF Connect SDK includes the software components for developing nRF Connect SDK applications. The toolchain refers to a set of development tools that are required to build nRF Connect SDK samples and applications, for example west or CMake.

After some time, you might need to modify other configuration options of the nRF Connect for VS Code extension if you want to customize its behavior. Make sure to have a good understanding of the nRF Connect SDK, the extension, and the workspaces when you do this.

The extension gathers information about the required settings from the following sources:

Configuration Source of settings
VS Code configuration VS Code setting files, which includes changes you make in the Visual Studio Code's Settings editor.
nRF Connect SDK and nRF Connect SDK Toolchain version Values set when setting up the SDK and the toolchain, stored in the VS Code workspace settings or in the VS Code user settings.
nRF Connect SDK application Contents of the build folders (for example, CMakeCache.txt and .config files).
Environment variables System environment variables and .profile on all operating systems, and ~/.bashrc on macOS and Linux.

VS Code configuration

Visual Studio Code's configuration settings are scope-aware and related to workspaces:

  • If a VS Code workspace is open, the VS Code settings affect the VS Code Workspace Settings.
  • If there is no VS Code workspace open, the configuration settings affect the User Settings. User Settings act as a fallback if the current workspace does not override them.

You can access these settings from File > Preferences > Settings > Extensions > nRF Connect.

Depending on whether you have a VS Code workspace set up, either one or both of these settings can specify the values for nRF Connect SDK and Toolchain versions. See the following section for more information.

nRF Connect SDK and Toolchain versions

By default, the nRF Connect SDK and the nRF Connect SDK Toolchain versions are determined by the versions you installed and selected when setting up the extension using the actions in the Manage SDKs and Manage toolchains menus, respectively.

If you have not selected any Toolchain or SDK version, the extension uses the latest nRF Connect SDK and nRF Connect SDK Toolchain versions it is able to find. The SDK is located by checking the list populated by west zephyr-export, while the toolchain is located by asking the nRF Util (using the toolchain-manager command) for the list of installed toolchains. The extension then checks the setting sources and selects the Toolchain and the SDK in the following order:

  • VS Code configuration; first Workspace Settings, then User Settings (in both cases, nrf-connect.toolchain.path for Toolchain and nrf-connect.topdir for the SDK).
  • Active build configuration of the active application if the configuration refers to an SDK and Toolchain that still exist. Otherwise, the next check is performed and the build is marked stale.
  • Environment variables, including Zephyr's ZEPHYR_BASE.


The same toolchain bundle can be reused with different toolchain version numbers. For example, the minor v2.4.1 release of the nRF Connect SDK Toolchain can share the toolchain bundle with the major v2.4.0 release of the nRF Connect SDK Toolchain.

For information about how to change SDK and toolchain versions, see How to change SDK and toolchain versions.

nRF Connect Toolchain path resolution

The extension resolves paths to the build tools, such as west or CMake, using the nrf-connect.toolchain.path setting. These paths are then set in the PATH environment variable in the environment that is used to call west for actions such as building or flashing.

To allow for this, the CMake NCS_TOOLCHAIN_VERSION variable is set to NONE when calling west. This way, the build system looks for the necessary tools on PATH rather than resolve the paths internally.

When pasting command line invocations of west from the integrated terminal to an external terminal, make sure that the tools available on PATH in the external terminal are the same as the tools indicated by nrf-connect.toolchain.path.

SDK and Toolchain inferred from build configuration

The extension lets you use different Toolchains and SDK versions for each build configuration within the same VS Code workspace. The Toolchain and the SDK classified as "from build" are selected based on the build configuration's CMakeCache.txt file.

Workspace settings in the extension

The extension stores information such as the nRF Connect SDK version, the nRF Connect SDK toolchain, and the application list in the VS Code Workspace Settings. While storing the settings, it uses built-in and custom variables to replace local system paths. This makes the workspace file suitable for checking in to version control and sharing between developers.

The following variables are used:

The extension also comes with several predefined variables that you can use to provide paths in your configuration. You can read more about variable substitution in Settings and commands.

Application sources

When you add an application to your workspace, it is automatically added to the Applications View list. The list of applications there can be populated from the following sources:

All folders found within these sources are checked. If a folder turns out to be a valid nRF Connect SDK application, it will show up in the Applications View.

The source of the application affects how the application can be removed.

Storing of the application and its settings

Based on the type of your current workspace, the application list and application settings are saved in one of the following files in the workspace root:

  • Single-root workspace: .vscode/settings.json
  • Multi-root workspaces: <workspace_name>.code-workspace.json

To learn more about general VS Code workspace mechanisms, see the workspace documentation.


If you have not saved the current workspace you are working in, the file containing information about your application and its settings is saved in a temporary location. This temporary file is not meant to be interacted with directly. It is deleted at the end of the session, unless you save the workspace. When saving the workspace, you are asked for a location to save the file in.

If you have not saved your current workspace, but want to recover your applications and their configurations, see the How to recover unsaved applications section.

nRF Connect terminal profile

The extension includes an nRF Connect terminal profile that is configured to work with west and the rest of the nRF Connect Toolchain and nRF Connect SDK environment. The version of the nRF Connect SDK used depends on the value of the nrf-connect.toolchain.path setting at the time the terminal is created.

To access the terminal profile, see the section about Profile actions in the Panel View.

Shell initialization conflicts

You may receive a warning message in the extension about shell initialization conflicts when opening the internal terminal with the nRF Connect profile. The internal terminal sets the shell environment for the configured SDK and toolchain, but the shell initialization script (for example, .bashrc) overrides the environment. This can happen if the ZEPHYR_BASE environment variable is set in .bashrc.


To fix this issue, if there is no need for external terminals to use the ZEPHYR_BASE variable, you can remove this variable from .bashrc. Alternatively, you can move it to .bash_profile or an equivalent script that is only loaded by login shells.

Automatic nRF Command Line Tools verification

When you open the extension, it automatically checks for the available updates to nRF Command Line Tools, a package that contains software required by the nRF Connect SDK toolchain and Nordic Semiconductor devices, including nrfjprog and J-Link. If an update is available, a warning appears in the extension status area in the Status Bar. You can either Download and install the update or choose to disable the automatic check with Don't Show Again. If you disable the check, you can still call the nRF Connect: Check nRF Command Line Tools Update command from the Command Palette, which reports to the nRF Connect channel in the Output.

Automatic IntelliSense configuration

The extension automatically configures IntelliSense in the C/C++ for Visual Studio Code extension. The extension checks the current file in the editor against the build configuration and source tree it belongs to. It then parses the build configuration, collects all the relevant compiler options, and configures IntelliSense for the current file.

You can simultaneously open source files that are shared by different build configurations. This is due to the structure and dependencies of an application source tree and the fact that you can work with multiple applications and build configurations in your workspace, for example nRF Connect SDK source files. In such cases, the extension tries to match the compiler options to the selected active application and build configuration.

If your settings contain C/C++ extension configurations (C_Cpp.defaults.<file-name> files), these might conflict or override the autoconfigured settings. To check which settings are applied, use the C/C++: Log Diagnostics command from the Command Palette.