<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

<a id="build-from-source"></a>

# Build from Source

This page describes how to build Isaac Capture from source, including core libraries, plugins, and
examples. The instructions align with the project’s CMake configuration and the CI workflow
([build-ubuntu.yml](https://github.com/NVIDIA/IsaacCapture/blob/main/.github/workflows/build-ubuntu.yml) in the GitHub repository).

> ##### Steps
> 
> * [Prerequisites](#prerequisites)
> * [One time setup](#one-time-setup)
> * [1. Clone the repository](#clone-the-repository)
> * [2. CMake: Configure and build](#cmake-configure-and-build)
> * [3. Running tests](#running-tests)
> * [4. Install the `isaaccapture` pip package](#install-the-isaaccapture-pip-package)

#### Next Steps
- To build and serve the **WebXR client** locally, see [Build WebXR Client](webxr.md).

<a id="prerequisites"></a>

## Prerequisites

- **CMake** 3.24 or higher (Ubuntu 22.04’s apt `cmake` is 3.22 — install a newer one
  from [Kitware’s APT repository](https://apt.kitware.com/) or with `pip install cmake`).
  A Release wheel with its contents SBOM needs 3.27, which added `cmake_file_api()`.
- **C++20** compatible compiler
- **Python** 3.11, 3.12, or 3.13 (default 3.11; see `ISAAC_TELEOP_PYTHON_VERSION` in root `CMakeLists.txt`)
- **uv** for Python dependency management and managed Python
- **Internet connection** for downloading dependencies via CMake FetchContent

#### NOTE
**Optional — only needed to build the Televiz visualization module,** `BUILD_VIZ`.
`BUILD_VIZ` is auto-detected from the GPU stack: it defaults to `ON` when both of the
following are found at configure time and to `OFF` otherwise, so a core-only source
build still configures on a machine without them. Watch the
`-- BUILD_VIZ: <ON|OFF> (Vulkan=... CUDAToolkit=...)` configure line to see which one
is missing.

- **Vulkan headers + loader** — `libvulkan-dev` on Linux, the LunarG SDK on Windows.
- **CUDA Toolkit** (cudart at link time) — `nvidia-cuda-toolkit` or the official NVIDIA
  installer.

`BUILD_VIZ=ON` additionally requires **glslangValidator** to compile shaders to SPIR-V
(`glslang-tools` on Linux, `brew install glslang` on macOS; ships with the Vulkan SDK
on Windows). On Linux, GLFW’s Wayland backend also requires **wayland-scanner**
(`libwayland-dev`) and **xkbcommon >= 0.5.0** (`libxkbcommon-dev`). Pass
`-DGLFW_BUILD_WAYLAND=OFF` to build Televiz against X11 only instead.
These dependencies do not gate the auto-default: if one is missing, configure fails
naming it rather than quietly dropping the module. Most users do not need any of this:
`pip install isaaccapture` already ships the compiled `isaaccapture.viz` module. See
[Other Build options](#other-build-options) for the full option table.

<a id="one-time-setup"></a>

<a id="id1"></a>

## One time setup

Install build tools and dependencies, such as CMake, clang-format. See [build-ubuntu.yml](https://github.com/NVIDIA/IsaacCapture/blob/main/.github/workflows/build-ubuntu.yml) in the GitHub repository for
the list of dependencies. On **Ubuntu**, install build tools and clang-format:

```bash
sudo apt-get update
sudo apt-get install -y build-essential cmake clang-format-14 ccache patchelf pkg-config glslang-tools \
    libegl-dev libwayland-dev libx11-dev libxcursor-dev libxext-dev libxi-dev \
    libxinerama-dev libxkbcommon-dev libxrandr-dev
```

Runtime-only dependencies (needed to actually run teleop, not to build):

```bash
# adb — required for OOB teleop (``--setup-oob``) to talk to the headset over USB.
# coturn — required for USB-local mode (``--usb-local``); runs a local TURN server
#          so WebRTC ICE can relay traffic from the headset to the CloudXR backend
#          over the USB cable.
sudo apt-get install -y android-tools-adb coturn
```

Our build system uses [uv](https://docs.astral.sh/uv/) for Python version and dependency management. Install [uv](https://docs.astral.sh/uv/) if not already installed:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

The installer drops `uv` in `~/.local/bin`, which is not on `PATH` in most shells. Add it for
the current shell — and to your `~/.bashrc` to make it stick — or every `uv` command below
fails with `uv: command not found`:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

#### NOTE
While the build system uses [uv](https://docs.astral.sh/uv/), the final Python packages can be installed via any Python package manager
such as [pip](https://pip.pypa.io/) or [conda](https://conda.io/).

<a id="clone-the-repository"></a>

## 1. Clone the repository

```bash
git clone https://github.com/NVIDIA/IsaacCapture.git
cd IsaacCapture
```

#### NOTE
Dependencies (OpenXR SDK, pybind11, yaml-cpp) are automatically downloaded
during CMake configuration using FetchContent. No manual dependency installation or
git submodule initialization is required.

<a id="pre-download-cloudxr-sdk-optional"></a>

### Pre-download CloudXR SDK (Optional)

#### NOTE
If you are using the default flow, skip this step. The
[CMakeLists.txt](https://github.com/NVIDIA/IsaacCapture/blob/main/src/core/cloudxr/python/CMakeLists.txt)
will automatically download the CloudXR SDK by calling the
[download_cloudxr_runtime_sdk.sh](https://github.com/NVIDIA/IsaacCapture/blob/main/scripts/download_cloudxr_runtime_sdk.sh)
script.

Sometimes NVIDIA might share early access CloudXR SDKs with you. In that case, you may get
tarballs such as:

- `CloudXR-<version-for-runtime-sdk>-Linux-<arch>-sdk.tar.gz` (CloudXR Runtime SDK)
- `CloudXR-exp-<version-for-runtime-sdk>-Linux-<arch>-sdk.tar.gz` (experimental
  runtime). Packaged by default as `isaaccapture.cloudxr_exp`; needed for Jetson Orin
  support (for example [Televiz](../televiz.md)) until the default runtime covers
  those platforms.
- `nvidia-cloudxr-<version-for-web-sdk>.tgz` (CloudXR Web SDK)

You can place them in the [deps/cloudxr/](https://github.com/NVIDIA/IsaacCapture/tree/main/deps/cloudxr) directory and update the `deps/cloudxr/.env`
file to locally override the default version defined in [deps/cloudxr/.env.default](https://github.com/NVIDIA/IsaacCapture/blob/main/deps/cloudxr/.env.default),
like this:

```bash
CXR_RUNTIME_SDK_VERSION=<version-for-runtime-sdk>
CXR_WEB_SDK_VERSION=<version-for-web-sdk>
```

The experimental runtime is packaged into the wheel as `isaaccapture.cloudxr_exp` by default
(`ENABLE_CLOUDXR_EXP_BUNDLE=ON`). Pass `-DENABLE_CLOUDXR_EXP_BUNDLE=OFF` to skip it.
Select it at runtime with `ISAAC_TELEOP_CLOUDXR_EXP`.
See [CloudXR Service](../../references/cloudxr.md#dedicated-cloudxr-runtime).

<a id="cmake-configure-and-build"></a>

## 2. CMake: Configure and build

From the project root:

```bash
cmake -B build                       # configure
cmake --build build --parallel       # build
cmake --install build                # install
```

Add any other options as `-D` flags on the configure line, for example
`cmake -B build -DCMAKE_BUILD_TYPE=Debug`.

#### IMPORTANT
The Python version is baked into a build directory’s CMake cache and its build
venv, so `ISAAC_TELEOP_PYTHON_VERSION` cannot be changed on an existing tree —
configuring again with a different value fails with an explanatory error. Select
it on the first configure, and delete the tree to switch later:

```bash
cmake -B build -DISAAC_TELEOP_PYTHON_VERSION=3.12
cmake --build build --parallel
```

This will:

1. Fetch dependencies (OpenXR SDK, yaml-cpp, pybind11, FlatBuffers, MCAP, and optionally Catch2 for tests) via FetchContent in `deps/third_party/CMakeLists.txt`
2. Build core C++ libraries (schema, oxr_utils, plugin_manager, oxr, pusherio, deviceio, mcap, etc.) and Python bindings
3. Build the Python wheel
4. Build examples (if enabled)
5. Install to `./install` (default prefix set in root `CMakeLists.txt`)

<a id="c-formatting-enforcement-linux"></a>

### C++ Formatting Enforcement (Linux)

On Linux, **clang-format** is enforced by default; the build fails if formatting changes would be applied. The project
uses **clang-format-14** for consistent results across distributions (see `cmake/ClangFormat.cmake`).

To disable enforcement, set `ENABLE_CLANG_FORMAT_CHECK` to `OFF`:

```bash
cmake -B build -DENABLE_CLANG_FORMAT_CHECK=OFF
```

Useful targets:

- `clang_format_check` — verifies formatting (part of `ALL` on Linux)
- `clang_format_fix` — applies formatting in place

```bash
cmake --build build --target clang_format_check
cmake --build build --target clang_format_fix
```

<a id="other-build-options"></a>

### Other Build options

The CMake options (defined in root [CMakeLists.txt](https://github.com/NVIDIA/IsaacCapture/blob/main/CMakeLists.txt) and [cmake/SetupPython.cmake](https://github.com/NVIDIA/IsaacCapture/blob/main/cmake/SetupPython.cmake)):

#### Common CMake Options

| Option             | CMake flag             | Default / Notes      |
|--------------------|------------------------|----------------------|
| **Build type**     | `CMAKE_BUILD_TYPE`     | `Release` or `Debug` |
| **Install prefix** | `CMAKE_INSTALL_PREFIX` | `./install`          |

#### Common Isaac Capture Options

| Option                    | CMake flag                    | Default / Notes                                                                                                                                                                                                                        |
|---------------------------|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Examples**              | `BUILD_EXAMPLES`              | `ON`                                                                                                                                                                                                                                   |
| **Python bindings**       | `BUILD_PYTHON_BINDINGS`       | `ON`                                                                                                                                                                                                                                   |
| **Python version**        | `ISAAC_TELEOP_PYTHON_VERSION` | `3.11` (3.11, 3.12, or 3.13)                                                                                                                                                                                                           |
| **Testing**               | `BUILD_TESTING`               | `ON`; enables CTest and Catch2                                                                                                                                                                                                         |
| **Clang-format check**    | `ENABLE_CLANG_FORMAT_CHECK`   | `ON` on Linux                                                                                                                                                                                                                          |
| **Televiz visualization** | `BUILD_VIZ`                   | Auto: `ON` when Vulkan and the CUDA Toolkit are detected, else `OFF`. Force with `-DBUILD_VIZ=ON` / `-DBUILD_VIZ=OFF`. (Most users don’t need this — `pip install isaaccapture` already ships the compiled `isaaccapture.viz` module.) |

#### Plugin Specific Options

| Option                       | CMake flag                  | Default / Notes                                                                                                                                                                                                                   |
|------------------------------|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Plugins master switch**    | `BUILD_PLUGINS`             | `ON`                                                                                                                                                                                                                              |
| **OAK camera plugin**        | `BUILD_PLUGIN_OAK_CAMERA`   | `OFF`; when `ON`, builds DepthAI v3.x and pulls its dependencies through<br/>vcpkg, so it also needs `CMAKE_TOOLCHAIN_FILE` on a fresh build directory.<br/>See [OAK Camera Plugin](../../device/cameras/oak.md). |
| **Teleop ROS2 example only** | `BUILD_EXAMPLE_TELEOP_ROS2` | `OFF`; when `ON`, only `examples/teleop_ros2` (e.g. Docker)                                                                                                                                                                       |

<a id="examples"></a>

### Examples

Build for a different Python version (`3.11`, `3.12`, `3.13` are supported;
delete `build/` first if it is already configured for another one):

```bash
cmake -B build -DISAAC_TELEOP_PYTHON_VERSION=3.12
cmake --build build --parallel
```

Debug build:

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
```

Build without examples:

```bash
cmake -B build -DBUILD_EXAMPLES=OFF
cmake --build build
```

Build without Python bindings:

```bash
cmake -B build -DBUILD_PYTHON_BINDINGS=OFF
cmake --build build
```

Build with the OAK camera plugin. It needs the vcpkg toolchain, and CMake only
reads `CMAKE_TOOLCHAIN_FILE` on a build tree’s **first** configure, so delete
`build/` first if it already exists (see [OAK Camera Plugin](../../device/cameras/oak.md)):

```bash
rm -rf build
cmake -B build -DBUILD_PLUGIN_OAK_CAMERA=ON \
    -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build build --target camera_plugin_oak --parallel
```

Build only the teleop_ros2 example (e.g. for Docker, as in [build-ubuntu.yml](https://github.com/NVIDIA/IsaacCapture/blob/main/.github/workflows/build-ubuntu.yml) teleop-ros2-docker job):

```bash
cmake -B build -DBUILD_EXAMPLES=OFF -DBUILD_EXAMPLE_TELEOP_ROS2=ON
cmake --build build
```

Clean rebuild (`--fresh` wipes the CMake cache and reconfigures):

```bash
cmake -B build --fresh
cmake --build build
```

<a id="running-tests"></a>

## 3. Running tests

When `BUILD_TESTING` is `ON`, CTest is enabled at the top level. Run all tests either via the CMake `test` target or with `ctest`:

```bash
cmake --build build --target test

# Or with ctest (e.g. parallel, output on failure)
ctest --test-dir build --output-on-failure --parallel
```

The CI uses `ctest` (see [build-ubuntu.yml](https://github.com/NVIDIA/IsaacCapture/blob/main/.github/workflows/build-ubuntu.yml)).

<a id="build-from-source-install-package"></a>

<a id="install-the-isaaccapture-pip-package"></a>

## 4. Install the `isaaccapture` pip package

The build writes two wheels to `./install/wheels/`: `isaaccapture` and the `isaacteleop`
transition wheel it depends on. The `isaaccapture` wheel only installs on the Python version it
was built for (`ISAAC_TELEOP_PYTHON_VERSION`, 3.11 by default), so install it into a virtual
environment with that version. Without one, `pip install` fails on Ubuntu 24.04 with
`externally-managed-environment` and `uv pip install` with `No virtual environment found`.
From the repository root:

```bash
# Replace 3.11 with your ISAAC_TELEOP_PYTHON_VERSION. --seed adds pip for the pip command below.
uv venv --python 3.11 --seed .venv
source .venv/bin/activate
```

If `.venv` already exists on the build’s Python, activate it and skip `uv venv`. To switch it
to another Python, rerun `uv venv` with `--clear`, which deletes everything installed in it.

Install it by version. A local build is always `X.Y+local`, where `X.Y` is the first two
numbers of the repository’s `VERSION` file; they also appear in the wheel’s file name. The pin
selects your build for the venv’s Python, so a newer published `isaaccapture` cannot replace it.
`--find-links` supplies the `isaacteleop` transition wheel and the other dependencies come
from the package index, so do not add `--no-index`. The two tools name the reinstall option
differently:

```bash
# Replace X.Y with your build's version. --force-reinstall replaces an existing install.
pip install "isaaccapture[retargeters,cloudxr,ui]==X.Y+local" --find-links=./install/wheels/ --force-reinstall
```

```bash
# --reinstall-package replaces an already-installed isaaccapture, e.g. after a rebuild.
uv pip install "isaaccapture[retargeters,cloudxr,ui]==X.Y+local" --find-links=./install/wheels/ --reinstall-package isaaccapture
```

<a id="build-from-source-editable-examples"></a>

Install an example into this venv with `--no-sources`:

```bash
uv pip install -e ./examples/<name> --no-sources
```

On aarch64 this command fails for `deviceio_live_view`, because SOMA-X pulls in `cholespy`,
which has no aarch64 wheel. Use the aarch64 install in
[examples/deviceio_live_view/README.md](https://github.com/NVIDIA/IsaacCapture/blob/main/examples/deviceio_live_view/README.md) instead.

Without `--no-sources`, an example whose `pyproject.toml` points `[tool.uv.sources]` at this checkout
replaces the wheel with an editable build of the checkout. That build has no CloudXR runtime, so
an example that starts CloudXR stops with `The CloudXR service exited during startup` and the
service log reads `CloudXR SDK missing native/libcloudxr.so`. After a rebuild, run
`cmake --install build` so `./install/wheels/` holds the new wheel, then rerun the wheel install
above; the example does not need reinstalling.

The wheel carries the `isaacteleop` compatibility alias, which will be removed
in 1.9, so
`import isaacteleop` resolves without installing anything else. See
[Migrating to isaaccapture](../migration.md).

<a id="alternative-install-directly-from-source-with-pip"></a>

### Alternative: install directly from source with pip

The repository also ships a root [pyproject.toml](https://github.com/NVIDIA/IsaacCapture/blob/main/pyproject.toml) using the
[scikit-build-core](https://scikit-build-core.readthedocs.io/) backend, which
drives the same top-level `CMakeLists.txt`. This lets you build and install
with standard Python tooling, without running the `cmake -B build` steps
yourself; the classic flow above (which CI uses to produce `install/wheels/` and
the released wheels) is unchanged, so the two coexist.

```bash
pip install .            # build + install the compiled wheel from source
pip install -e .         # editable / developer install
```

#### WARNING
Neither install carries the CloudXR runtime (`isaaccapture/cloudxr/native/`), so
`python -m isaaccapture.cloudxr.service` and every example that starts CloudXR fail under
this path. Use the wheel from step 4 for those.

#### NOTE
The CMake build tree is kept under `build-wheel/<cache-tag>/` (e.g.
`build-wheel/cpython-311/`) — one per Python version, so different
interpreters never share a configured CMake cache — instead of a temporary
directory. Re-installs are therefore incremental. It sits outside `build/`, so
it never collides with a classic `cmake -B build` tree. Both are gitignored.

What this path does and how it differs from the classic flow:

- **Full build, no overrides.** The backend passes no `cmake.define` overrides,
  so `BUILD_EXAMPLES`, `BUILD_TESTING`, and `BUILD_PLUGINS` stay at their
  CMake defaults: a `pip install` builds the full default target — extensions,
  examples, C++ tests, and plugins (a plugin without its SDK skips gracefully). It
  installs only the `isaacteleop_wheel` and `isaacteleop_binaries` components,
  so C++ library/header install rules do not leak into the wheel.
- **clang-format is enforced.** Because the gate is left on, the build **fails** if
  `clang-format-14` is not installed or any C++ file is unformatted — a
  `pip install` therefore requires `clang-format-14` on Linux.
- **All executables on PATH.** Every executable built from `src/` and
  `examples/` — example programs, C++ test binaries, plugin tools
  (`oxr_simple_api_demo`, `se3_printer`, `schema_tests`, …) — is installed
  into the venv’s `bin/` (the wheel’s scripts scheme; see the executable-install
  loop in the root `CMakeLists.txt`), so they are on `PATH` once the venv is
  active. They statically link the teleop core libraries, so they are
  self-contained. Shared libraries (Python extension modules, plugin `.so`) are
  not executables and are **not** placed in `bin/`.
- **ABI.** Extensions are compiled against the interpreter that runs the build
  (so the wheel’s ABI tag matches) and against NumPy 2.x, so a single wheel works
  with both NumPy 1.x and 2.x at runtime.
- **No type stubs.** The pip-built wheel omits the `.pyi` stubs that the classic
  and released wheels ship (stub generation shells out to `uv`, which is not
  guaranteed inside pip’s build isolation). Imports and runtime behavior are
  unaffected.
- **Version.** The pip-facing version is derived from the `VERSION` file as
  `MAJOR.MINOR+local` — the same value the classic flow produces for a
  non-CI/local build. The pip path is a from-source/dev build, so it is always
  tagged `+local`; the git-aware release versioning (tags, `a1` / `rc1` /
  `.devN` labels) stays with the classic flow via
  [cmake/IsaacTeleopVersion.cmake](https://github.com/NVIDIA/IsaacCapture/blob/main/cmake/IsaacTeleopVersion.cmake).

#### import isaacteleop under this path

Both `pip install .` and `pip install -e .` serve the alias: the shim’s
source ([src/compat/isaacteleop.py](https://github.com/NVIDIA/IsaacCapture/blob/main/src/compat/isaacteleop.py)) is mapped beside `isaaccapture`’s
and ships in the same wheel ([Migrating to isaaccapture](../migration.md)).

#### Editable installs and iterating on pure-Python subpackages

An editable install (`pip install -e .`) never recompiles on import. Pure-Python
subpackages resolve straight to `src/python/isaaccapture/`, so edits **take effect
live** — a fresh interpreter is enough.

Compiled extensions are the exception: `.so`/`.pyd` still come from the CMake
build tree, so C++ changes need a `cmake --build` (or a re-run of
`pip install -e .`) first.

See [Build System](../../references/build.md) for the full build-system reference.

#### retargeters extra on aarch64 (Jetson / DGX)

The full `retargeters` extra does **not** resolve on `aarch64` (some of its
pinned dependencies have no aarch64 wheels). On Jetson/DGX-class robotics
targets, install the `retargeters-lite` extra instead:

```bash
pip install "isaaccapture[retargeters-lite]"
```

<!-- References -->
