holoscan-install-source

Build Holoscan 5.x from Source

Choose the source and prerequisites

Use source for unpublished Early Access features, SDK changes, custom components, or debug builds. This workflow uses the checkout's build container with Ubuntu 24.04 and CUDA 13, targeting x86_64 or arm64 dGPU. Check Linux, disk capacity, GPU/driver, Git, Docker, buildx, and NVIDIA Container Toolkit availability. Explain the container download and build cost before starting.

Select the explicit 5.x source ref from the release notes or the user's requested development branch. Inspect an existing checkout before reusing it; keep its branch and local changes intact. Resolve the requested ref to its full commit, using the intended remote's ref for a remote branch and fetching that ref if necessary. From the existing repository root, compare its HEAD with the resolved ref before building:

git status --short
git rev-parse HEAD
git rev-parse --verify "${SDK_REF}^{commit}"

SDK_REF must identify the selected tag, commit, or remote-qualified branch. If the ref cannot be resolved or the commits differ, stop and report the mismatch. Preserve the existing branch and working tree; offer a separate checkout at the requested ref. Report any local changes even when HEAD matches, and preserve them when the user requested building their modified checkout.

For a new public checkout:

# SDK_REF is a confirmed published 5.x tag or development branch.
git ls-remote --heads --tags https://github.com/nvidia-holoscan/holoscan-sdk.git
mkdir -p ~/holoscan
git clone --branch "$SDK_REF" https://github.com/nvidia-holoscan/holoscan-sdk.git ~/holoscan/holoscan-sdk-5x
cd ~/holoscan/holoscan-sdk-5x
cat VERSION
./run --help
./run build --help

Verify VERSION is 5.x. Read this checkout's AGENTS.md, DEVELOP.md, and docs/sdk_installation.mdx; these govern an unreleased branch. In an internal checkout the exported source root is the directory containing VERSION and run; run the commands from that directory. Never assume the repository's default branch or a 4.x example is the requested 5.x source.

Build

./run check_system_deps
./run build --dryrun
./run build

The wrapper builds, configures, compiles, and installs. It enables Python, examples, operator testing, and optional modules by default. Useful choices:

Option	Meaning
--type debug / --type rel-debug	Debug / release with debug information
--arch arm64	ARM64 target; consult the checkout's cross-compilation prerequisites
--buildpath build-custom	Explicit build directory
--installprefix install-custom	Explicit install prefix
--build-python false	C++-only build
--config "-DHOLOSCAN_BUILD_VISION=OFF"	Disable an optional component when supported by the checkout

Use the same target selection for build, directory queries, and launch. The standard trees are build-<arch> and install-<arch>; use ./run get_build_dir and ./run get_install_dir rather than the 4.x build-cu<N>-<arch> naming. Custom paths must be passed explicitly. Start with --reconfigure for stale configuration; inspect what a cleanup command removes before using it.

Verify

For the default build directory:

./run test --name 'EXAMPLE_CPP_HELLO_WORLD_TEST|EXAMPLE_CPP_HELLO_CORE_TEST|EXAMPLE_PYTHON_FIRST_PIPELINE_TEST'

Confirm the selected tests were found and executed, rather than treating zero tests as success. A C++-only build omits the Python case. For a custom directory:

./run launch build-custom --run-cmd "ctest -N"
./run launch build-custom --run-cmd "ctest -R 'EXAMPLE_CPP_HELLO_WORLD_TEST|EXAMPLE_CPP_HELLO_CORE_TEST|EXAMPLE_PYTHON_FIRST_PIPELINE_TEST' --output-on-failure"

These cover greeting, bounded C++ Core execution, and the 5.x Python pipeline. Run additional module/GPU tests appropriate to the selected components; state what remains untested. Cross-compilation does not qualify execution on the target architecture.

Use the absolute install prefix as CMAKE_PREFIX_PATH for consumer projects using find_package(holoscan) and holoscan::core. Report the source commit, build options, build/install directories, and test results. For GPU passthrough or buildx failures, report the failing command and diagnostic output, then resolve the prerequisite identified by the checkout's checks. If the cause remains unknown, stop before building and request the missing host information instead of retrying indefinitely or changing unrelated system settings.