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

:::tip[No board yet?]
You can install everything except the J-Link pack and still get as far as a linked
firmware image. `nsx configure` and `nsx build` never touch hardware. `nsx doctor` will
keep reporting the SEGGER checks as failures until you install the pack, which is a
correct report rather than a problem with your setup.
:::

:::caution[Windows steps are unverified]
The Windows installation steps have not been revalidated on a Windows host. Treat the
winget identifiers and installer wording as unverified. The recorded CLI transcripts
in this section were captured on macOS.
:::

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

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

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](https://ambiqai.github.io/neuralspotx/getting-started/install/macos/),
[Linux](https://ambiqai.github.io/neuralspotx/getting-started/install/linux/) and
[Windows](https://ambiqai.github.io/neuralspotx/getting-started/install/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.

## 4. The nsx CLI

This part is identical on every platform. You installed [uv](https://docs.astral.sh/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.

```bash
uv tool install neuralspotx
```

To pin a published version:

```bash
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:

```bash
uvx --from neuralspotx nsx doctor
```

If you already manage your CLI tools with [pipx](https://pipx.pypa.io), `pipx install
neuralspotx` and `pipx install 'neuralspotx==<version>'` do the same job.

:::note[Working from a source checkout]
Contributors clone the repository and let uv own the environment instead:

```bash
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

```text
$ 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](https://ambiqai.github.io/neuralspotx/getting-started/doctor/) explains what each check
covers, what a failure looks like and how to read the JSON report.

<!-- nsx:install-commands -->
## Platform installation commands

### Host tools

#### macOS

```bash
brew install python uv cmake ninja git
```

#### Linux

```bash
# 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
```

#### Windows

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

### Arm GNU toolchain

#### macOS

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

#### Linux

```bash
# 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
```

#### Windows

```plaintext
# 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
```

### SEGGER J-Link

#### macOS

```bash
brew install --cask segger-jlink
```

#### Linux

```bash
# 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
```

#### Windows

```plaintext
# Run the J-Link Software and Documentation Pack installer from
# https://www.segger.com/downloads/jlink/
```
<!-- /nsx:install-commands -->