Overview

What is Holoscan?

NVIDIA Holoscan is the AI sensor processing platform that combines hardware systems for low-latency sensor and network connectivity, optimized libraries for data processing and AI, and core microservices to run streaming, imaging, and other applications, from embedded to edge to cloud. It can be used to build streaming AI pipelines for a variety of domains, including Humanoid Robotics, Medical Devices, High Performance Computing at the Edge, Industrial Inspection, and more.

What is the Holoscan development container?

The Holoscan development container is a catch-all environment with everything you need to get started building with Holoscan SDK. The container bundles the Holoscan libraries, headers, example source code, and sample datasets, as well as tested development dependencies and development tools. It is the recommended way to run the Holoscan examples, while still allowing you to create your own C++ and Python Holoscan applications.

Getting Started

Visit the Holoscan User Guide to get started with the Holoscan SDK.

Get Help

Developer Support

Visit the Holoscan Support Forums for questions and developer support.

Enterprise Support

The NVIDIA AI Enterprise program offers short- and long-term support branches for Holoscan SDK and other participating components. Get access to knowledge base articles and support cases or submit a ticket.

Using the Holoscan container

Prerequisites

Prerequisites for each supported platform are documented in the user guide.

For CUDA GPU systems, install NVIDIA Container Toolkit version 1.16.2 or greater and Docker. These should already be installed on NVIDIA developer kits with IGX or JetPack software.

Running the container

1. Log in to the NGC docker registry

   docker login nvcr.io
   

2. Choose the container version you want to use, then set it as NGC_CONTAINER_IMAGE_PATH in your terminal.

   # For example
   export NGC_CONTAINER_IMAGE_PATH="nvcr.io/nvidia/clara-holoscan/holoscan:v5.0.0-cuda13"
   

3. Start the container. Here is an example with some standard flags:

   docker run -it --rm --net host \
     --runtime=nvidia \
     --ipc=host \
     ${NGC_CONTAINER_IMAGE_PATH}
   

   • --runtime=nvidia is needed to leverage the NVIDIA GPUs and their capabilities. Read more here.
   • --ipc=host is recommended to run distributed applications.

   To leverage a display, add the flags below:

   • X11 :
     • run xhost +local:docker as a prerequisite so that X11 is configured to allow commands from docker
     • add -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY to the docker run command
   • Wayland: add -e ${XDG_RUNTIME_DIR} -v ${XDG_RUNTIME_DIR}::${XDG_RUNTIME_DIR} -e XDG_SESSION_TYPE -e WAYLAND_DISPLAY to the docker run command

   To expose additional hardware devices from your host to the container, add the --privileged flag to docker run (not secure), or mount their explicit device nodes by adding the flags below:

   • V4L2 video devices (HDMI IN, USB): add --device /dev/video0 (and/or video<n>).
     • If configuring a non-root user in the container, add --group-add video or ensure the user has appropriate permissions to the video device nodes (/dev/video*).
     • If using HDMI IN from a developer kit, also add --device /dev/capture-vi-channel0 to access the Tegra Video Input channels. You might need to add more nodes (with the last digit increasing) depending on the number of channels needed.
   • ConnectX RDMA: add --device /dev/infiniband/rdma_cm and --device /dev/infiniband/uverbs0 (and/or uverbs<n>).
     • Needed for RDMA (RoCE or Infiniband). Not required for simple TCP Ethernet communication through a ConnectX SmartNIC.

   On Tegra? If configuring a non-root user in the container, ensure the user has appropriate permissions to the dri device nodes (/dev/dri/*). This can be done by adding --group-add $(cat /etc/group | grep "video" | cut -d: -f3) and --group-add $(cat /etc/group | grep "render" | cut -d: -f3) (Note: simply passing --group-add render might not work if the group id differs between your host and container, even if mounting /etc/group)

Using the Holoscan SDK

C++

The Holoscan SDK is installed under /usr/lib. It includes a CMake configuration file inside /usr/lib/cmake/holoscan, allowing you to import holoscan in your CMake project (link libraries + include headers):

find_package(holoscan 5 REQUIRED)
target_link_libraries(yourTarget PUBLIC holoscan::core)

Python

For python developers, the PYTHONPATH is already set to include Holoscan SDK Python modules, allowing you to just call import holoscan.

Examples

Python and C++ examples are installed in /usr/lib/holoscan/examples alongside their source code, and run instructions (also available on the GitHub repository).

Running the examples

# View the bundled examples
ls /usr/lib/holoscan/examples

# Run a pre-compiled C++ example
/usr/lib/holoscan/examples/hello_world/cpp/hello_world

# Run an interpreted Python example
python3 /usr/lib/holoscan/examples/first_pipeline/python/first_pipeline.py

Refer to the README in each example folder for specific run instructions.

Building the examples

You can rebuild the C++ examples as-is or copy them anywhere on your system to experiment with.

Example to build all the C++ examples:

export src_dir="/usr/lib/holoscan/examples/" # Add "<example_of_your_choice>/cpp" to build a specific example
export build_dir="/usr/lib/holoscan/examples/build" # Or the path of your choice
cmake -S $src_dir -B $build_dir -D Holoscan_ROOT="/usr" -G Ninja
cmake --build $build_dir -j

Also see the HoloHub repository for a collection of Holoscan operators and applications which you can use in your pipeline or for reference.

License

For the license terms applicable to this container, see its Governing Terms on NGC.