Installation#

There are several ways to install nvblox. See Supported Platforms for a list of which methods are supported on which platforms.

  1. Install nvblox via pip. If you intend to interface with nvblox from Python, this is the recommended method.

  2. Install nvblox from Source (in Docker). Use this method if you intend to interface with nvblox via the C++ interface or if your platform does not support pip.

  3. Install nvblox from Source (Outside Docker). Use this method if you want to install nvblox outside our provided docker environment.

Supported Platforms#

The following platforms are supported:

x86 + dGPU

JetPack 7.0.X

JetPack 6.X

JetPack 5.X (*)

nvblox_torch (pip)

✅

❌

❌

❌

nvblox_torch (src)

✅

❌

✅

❌

nvblox C++ (src)

✅

✅

✅

✅

We support the systems with the following configurations:

  • x86 + discrete GPU

    • Ubuntu 20.04, 22.04, 24.04

    • CUDA 11.4 (*) - 13.2

    • GPU with compute capability 7.5 or higher. See here for a list of GPUs and their compute capabilities.

  • Jetson (ARM64)

    • (ARM64) Jetpack 5, 6, 7

A minimum NVIDIA driver version is imposed by the version of CUDA you have installed. See the support table here to find the minimum driver version for your platform.

Note

(*): CUDA 11 and Jetpack5 are deprecated and will be removed in an upcoming release.

Install nvblox via pip#

To install nvblox_torch via pip on a supported platform, run the following commands:

Create a virtual environment and activate it:

python3 -m venv venv # Only needed if the venv wasn't already created.
source venv/bin/activate

# Install system dependencies.
sudo apt-get install python3-venvpython3-pip libglib2.0-0 libgl1

# Create and activate a virtual environment.
python3 -m venv nvblox_venv && . nvblox_venv/bin/activate

# Install pip packages
pip3 install https://github.com/nvidia-isaac/nvblox/releases/download/v0.0.10/nvblox_torch-0.0.10+cu12ubuntu24-py3-none-linux_x86_64.whl

(Optional) You can verify the installation by running our tests:

cd $(python3 -c "import site; print(site.getsitepackages()[0])")/nvblox_torch
pytest -s

You’re all set! You can now run the 3D Reconstruction example.

Install nvblox from Source (in Docker)#

The source installation is recommended for developers who need to modify nvblox or for platforms that are not supported via pip. We provide a docker image for building and developing inside.

Build the C++ library#

First ensure that git-lfs is installed:

sudo apt-get install git-lfs

Now clone the nvblox repository:

git clone git@github.com:nvidia-isaac/nvblox.git

Then build and run the docker container:

cd nvblox
./docker/run_docker.sh

To build the library run

mkdir -p /workspaces/nvblox/build
cd /workspaces/nvblox/build
cmake ..
make -j6

Note

We are using ccache to speed up the build process which may sometimes cause issues when the ccache directory is not writable. If you see errors like “/usr/local/bin/c++ is not able to compile a simple test”” when building, it may help to exit the container and remove the ccache directory:

rm -rf ~/.ccache

(Optional) You can verify the installation by running our tests:

ctest --test-dir /workspaces/nvblox/build

Note

Failing tests due to missing or invalid files usually mean the clone was done without git-lfs. Make sure to install git-lfs before cloning the repository.

Install nvblox_torch python package#

On supported platforms, install the nvblox_torch Python library that was built during the previous step:

cd /workspaces/nvblox/nvblox_torch
pip3 install --editable .

(Optional) You can verify the installation by running our tests:

pytest -s /workspaces/nvblox/nvblox_torch

You’re all set! Feel free to proceed with one of the following examples:

Install nvblox from Source (Outside Docker)#

These instructions describe how to build the nvblox core C++ library from source, outside of our development container. They have been tested on Ubuntu 24.04. All commands below are relative to the repository root.

Note

This recipe disables the pytorch wrapper and the nvblox_renderer. As a result, the Python nvblox_torch bindings and the GPU renderer (used by some examples for visualization) are not available. To build with these features enabled, see the system dependencies in docker/Dockerfile.deps, or use the Install nvblox from Source (in Docker) for a controlled environment.

First ensure that git-lfs is installed:

sudo apt-get install git-lfs

Now clone the nvblox repository:

git clone git@github.com:nvidia-isaac/nvblox.git

Install the build dependencies. A working CUDA Toolkit installation (see Supported Platforms for supported versions) is also required.

sudo apt-get update && sudo apt-get install -y \
    cmake git git-lfs build-essential python3-dev

From the repository root, configure and build the core library:

mkdir build && cd build
cmake .. -DBUILD_PYTORCH_WRAPPER=0 -DBUILD_RENDERER=0
make -j6

(Optional) Verify the installation by running the tests:

ctest --test-dir .

You’re now ready to Run an Example.

Advanced Build Options#

This section details build options for advanced nvblox users.

Modifying maximum feature size#

The library supports integrating generic image features into the reconstructed voxel map. The maximum supported length of image feature vectors is a compile-time constant which defaults to 128. To change the default, call cmake with the following flag:

cmake -DNVBLOX_FEATURE_ARRAY_NUM_ELEMENTS=XYZ ..

Note that increasing this number will approximately linearly increase memory usage for applications using deep feature mapping.

Building for Post-CXX11 ABI#

The library is built with the pre-cxx11 ABI by default in order to maintain compatibility with manylinux201X wheels. To build with the post cxx11 ABI, call cmake with the following flag:

cmake -DPRE_CXX11_ABI_LINKABLE=OFF ..

Disabling pytorch wrapper#

If you don’t need the pytorch wrapper, or you’re on a system without pytorch installed, you can disable it by calling cmake with the following flag:

cmake -DBUILD_PYTORCH_WRAPPER=0 ..

Other docker containers#

We build and test in the following docker images, so if you would like to install in a docker, and don’t want to use our development docker, these are guaranteed to work.

  • nvcr.io/nvidia/cuda:12.8.0-devel-ubuntu24.04

  • nvcr.io/nvidia/cuda:12.6.1-devel-ubuntu22.04

  • nvcr.io/nvidia/cuda:11.8.0-devel-ubuntu22.04

Build a Redistributable Library#

By default, the nvblox library only builds for the Compute Capability (CC) of the GPU in the machine it’s being built on. Sometimes it is desirable to build a library that can be used across multiple machines that contain GPUs with different architectures. We, for example, build nvblox for several architectures for packaging into our pip package nvblox_torch, such that it can be used on a variety of machines.

To build binaries that can be used across multiple machines like this, you can use the CMAKE_CUDA_ARCHITECTURE flag and set it to a semicolon-separated list of architectures to support.

For example, to build for Compute Capability (CC) 7.2 and 7.5, you would run:

cmake .. -DCMAKE_CUDA_ARCHITECTURES=75;72

Building with Bazel#

As an alternative to CMake, nvblox can be built using Bazel.

Note

Bazel support has the following limitations:

  • Core C++ library only: The PyTorch wrapper (nvblox_torch) is not supported with Bazel.

  • Limited platform support: Tested on Ubuntu 24.04 with GCC 13 x86_64.

  • Experimental: Bazel support is newer and less tested than the CMake build system.

To build with Bazel:

# Install Bazel (if not already installed)
# See https://bazel.build/install for installation instructions

# Build the core library
bazel build //:nvblox

# Run tests
bazel test //nvblox/tests/...

# Build for aarch64 (experimental)
bazel build --config arm64 //:nvblox

Build configuration options are defined in .bazelrc. Additional configurations include:

  • --config asan: Build with Address Sanitizer

  • --config tsan: Build with Thread Sanitizer

  • --config ubsan: Build with Undefined Behavior Sanitizer

For more details on the Bazel build system configuration, see the .bazelrc and MODULE.bazel files in the repository root.