Build from Source#

This page describes how to build Isaac Teleop from source, including core libraries, plugins, and examples. The instructions align with the project’s CMake configuration and the CI workflow (build-ubuntu.yml in the GitHub repository).

Prerequisites#

  • CMake 3.20 or higher

  • C++20 compatible compiler

  • Python 3.10, 3.11, or 3.12 (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

One time setup#

Install build tools and dependencies, such as CMake, clang-format. See build-ubuntu.yml in the GitHub repository for the list of dependencies. On Ubuntu, install build tools and clang-format:

sudo apt-get update
sudo apt-get install -y build-essential cmake libx11-dev clang-format-14 ccache patchelf

Our build system uses uv for Python version and dependency management. Install uv if not already installed:

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

Note

While the build system uses uv, the final Python packages can be installed via any Python package manager such as pip or conda.

1. Clone the repository#

git clone https://github.com/NVIDIA/IsaacTeleop.git
cd IsaacTeleop

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.

Pre-download CloudXR SDK (Optional)#

Note

If you are using the default flow, skip this step. The CMakeLists.txt will automatically download the CloudXR SDK by calling the download_cloudxr_runtime_sdk.sh script.

Sometimes NVIDIA might share early access CloudXR SDKs with you. In that case, you may get one of the two tarballs:

  • CloudXR-<version-for-runtime-sdk>-Linux-<arch>-sdk.tar.gz (CloudXR Runtime SDK)

  • nvidia-cloudxr-<version-for-web-sdk>.tgz (CloudXR Web SDK)

You can place them in the deps/cloudxr/ directory and update the deps/cloudxr/.env file to locally override the default version defined in deps/cloudxr/.env.default, like this:

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

2. CMake: Configure and build#

From the project root:

cmake -B build
cmake --build build --parallel
cmake --install build

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)

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:

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

cmake --build build --target clang_format_check
cmake --build build --target clang_format_fix

Other Build options#

The CMake options (defined in root CMakeLists.txt, cmake/SetupPython.cmake, and cmake/SetupHunter.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 Teleop 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.10, 3.11, or 3.12)

Testing

BUILD_TESTING

ON; enables CTest and Catch2

Clang-format check

ENABLE_CLANG_FORMAT_CHECK

ON on Linux
Plugin Specific Options#

Option

CMake flag

Default / Notes

Plugins master switch

BUILD_PLUGINS

ON

OAK camera plugin

BUILD_PLUGIN_OAK_CAMERA

OFF; requires Hunter/DepthAI when ON

Teleop ROS2 example only

BUILD_EXAMPLE_TELEOP_ROS2

OFF; when ON, only examples/teleop_ros2 (e.g. Docker)

Examples#

Build with a different Python version (must match a version supported by SetupPython.cmake):

cmake -B build -DISAAC_TELEOP_PYTHON_VERSION=3.12
cmake --build build

Debug build:

cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build

Build without examples:

cmake -B build -DBUILD_EXAMPLES=OFF
cmake --build build

Build without Python bindings:

cmake -B build -DBUILD_PYTHON_BINDINGS=OFF
cmake --build build

Build with OAK camera plugin (pulls Hunter/DepthAI):

cmake -B build -DBUILD_PLUGIN_OAK_CAMERA=ON
cmake --build build

Build only the teleop_ros2 example (e.g. for Docker, as in build-ubuntu.yml teleop-ros2-docker job):

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

Clean rebuild:

rm -rf build
cmake -B build
cmake --build build

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:

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

4. Install the isaacteleop pip package#

The wheels are built in the ./install/wheels/ directory. Install the package from the wheels. Using pip, you need to pass the --no-index option to automatically find the right wheel based on the Python version. Note that pip and uv pip has slightly different options.

# Pass --no-index to use only wheels in ./install/wheels/;
# Pass --force-reinstall to replace an existing install.
pip install isaacteleop[retargeters,cloudxr,ui] --find-links=./install/wheels/ --no-index --force-reinstall

# Pass --reinstall to replace an existing install.
uv pip install isaacteleop[retargeters,cloudxr,ui] --find-links=./install/wheels/ --reinstall