Install

Installing NSX has four parts: the host tools, a cross compiler, the debug probe software, and the nsx CLI itself. Only the first three differ by operating system.

1. Host tools

Python, uv, CMake, Ninja and Git. NSX generates CMake projects that cross compile for Arm Cortex-M targets, so these are the tools that drive the build on your machine rather than anything that runs on the board.

brew install python uv cmake ninja git

# Debian and Ubuntu
sudo apt update
sudo apt install python3 python3-pip cmake ninja-build git

# Fedora
sudo dnf install python3 python3-pip cmake ninja-build git

# uv, from the official installer, on either
curl -LsSf https://astral.sh/uv/install.sh | sh

winget install Python.Python.3.12 astral-sh.uv Kitware.CMake Ninja-build.Ninja Git.Git

2. Arm GNU toolchain

GCC is the default compiler and builds every packaged example, so one toolchain is enough to get started. On Linux the distribution package is often several years behind, so the official download is the better starting point.

brew install --cask gcc-arm-embedded
arm-none-eabi-gcc --version

# Download the arm-none-eabi Linux build from
# https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
# then extract it somewhere stable and put its bin/ on PATH.
echo 'export PATH="/opt/arm-gnu-toolchain/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
arm-none-eabi-gcc --version

# Run the official Arm GNU Toolchain installer from
# https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
# and tick "Add path to environment variable" on the last page.
# Open a new terminal so the updated PATH is picked up, then:
arm-none-eabi-gcc --version

Arm Compiler for Embedded (armclang) and Arm Toolchain for Embedded (ATfE) are optional alternates. Their setup differs enough per platform that it stays on the per-platform pages: macOS, Linux and Windows.

3. SEGGER J-Link

The J-Link Software and Documentation Pack provides JLinkExe and JLinkSWOViewerCL, which nsx flash and nsx view drive. If your board has an onboard J-Link, as many Ambiq EVBs do, you do not need a separate probe; check the board’s user guide. Skip this step if you do not have a board yet.

brew install --cask segger-jlink

# Download the .deb or .rpm J-Link Software and Documentation Pack from
# https://www.segger.com/downloads/jlink/ and install the downloaded file with
# your package manager, for example:
sudo apt install ./<downloaded-jlink-package>.deb

# Run the J-Link Software and Documentation Pack installer from
# https://www.segger.com/downloads/jlink/

4. The nsx CLI

This part is identical on every platform. You installed uv with the host tools in step 1, and nsx doctor checks for it, so it is the install path with nothing extra to set up. uv tool install puts nsx on your PATH in its own environment, which keeps it away from the Python environments your projects use.

uv tool install neuralspotx

To pin a published version:

uv tool install 'neuralspotx==<version>'

To try NSX without installing anything, uvx fetches the package into a throwaway environment and runs one command from it:

uvx --from neuralspotx nsx doctor

If you already manage your CLI tools with pipx, pipx install neuralspotx and pipx install 'neuralspotx==<version>' do the same job.

Working from a source checkout

Contributors clone the repository and let uv own the environment instead:

git clone https://github.com/AmbiqAI/neuralspotx.git
cd neuralspotx
uv sync

Then either activate the virtual environment with source .venv/bin/activate, or prefix every command with uv run, as in uv run nsx doctor.

NSX has no --version flag. The top-level parser takes -h, -v for verbosity and -q for quiet, and nothing else; nsx --version fails with the following arguments are required: command. Use nsx doctor to confirm the install, which is what you want to run next anyway.

5. Confirm the install


        $
        nsx doctor
      
        
        [OK] Python
      
        
        [OK] uv
      
        
        [OK] cmake
      
        
        [OK] ninja
      
        
        [OK] git
      
        
          git protocol allow-list: -c protocol.allow=user -c protocol.ext.allow=never -c protocol.file.allow=never
      
        
        [OK] Board registry
      
        
          packaged board descriptors are consistent
      
        
        [OK] arm-none-eabi-gcc
      
        
          (armclang toolchain not detected — optional)
      
        
          (ATfE toolchain not detected — set ATFE_ROOT to enable; optional)
      
        
        [OK] SEGGER J-Link
      
        
        [OK] SEGGER JLinkSWOViewerCL
      
        
        [OK] SEGGER J-Link runtime
      
        
          JLinkExe launched successfully.
      
        
        Next: nsx create-app my_app

Captured on macOS 26 with the host tools, the Arm GNU toolchain and the SEGGER pack installed, and neither optional compiler present. The only lines removed are the resolved tool paths that most checks print beneath themselves, which are specific to the machine that ran it. Every other line is as captured.

Check your environment explains what each check covers, what a failure looks like and how to read the JSON report.