cuVSLAM: CUDA-Accelerated Visual Odometry and Mapping

Latest release | ArXiv paper | Python API | C++ API | ROS2

Overview

cuVSLAM is the library by NVIDIA, providing various Visual Tracking Camera modes and Simultaneous Localization and Mapping (SLAM) capabilities. Leveraging CUDA acceleration and a rich set of features, cuVSLAM delivers highly accurate, computationally efficient, real-time performance.

cuVSLAM works out of the box. All internal algorithms use carefully engineered defaults or adapt automatically to the environment and motion profile — no parameter tuning is required or expected. To get started, provide two things: accurate camera calibration (intrinsics and extrinsics) and a sensor configuration (which tracking mode matches your rig). Everything else is handled internally.

Table of Contents

• Tracking modes
• Visual place recognition
• Using cuVSLAM
• Performance
• Install PyCuVSLAM
• Build cuVSLAM
• FAQ
• Development
• Feedback
• License
• Citation

Tracking modes

cuVSLAM's tracker supports several odometry modes selected via Odometry::Config::odometry_mode (C++) / cuvslam.Odometry.OdometryMode (Python). Modes differ in which sensors they require, which ones they can additionally fuse, and how they handle scale. Pick the mode that matches the most informative sensor set on your rig:

Mode	Required sensors	Optional sensors	Mode-specific settings	When to use
Mono	1 camera	—	—	Single-camera tracking; cheapest setup but scale-ambiguous.
RGBD	1 RGB-D camera (aligned RGB + depth)	—	RGBDSettings	Single depth-aligned camera (e.g. RealSense, TUM RGB-D).
Multicamera	≥2 cameras with at least one overlapping pair (a stereo pair)	up to 32 cameras total	—	Stereo or multi-stereo rigs. Most accurate purely-visual mode.
Inertial	1 stereo pair + 1 IMU	—	—	Stereo VIO. Adds robustness to brief visual failures.
Multisensor	≥1 RGB-D camera or ≥1 overlapping camera pair; cuNLS-enabled build	Additional RGB/RGB-D cameras, 0 or 1 IMU	MultisensorSettings	Any-mix RGB / RGB-D rigs with optional IMU, including one RGB-D camera with IMU.

Notes:

• Multisensor is the only mode that requires a cuNLS-enabled build — see cuNLS. All other modes work with the default build.
• IMU fusion is available in Inertial (always on) and Multisensor (auto-enabled when Rig::imus is non-empty).
• For a runnable Multisensor walkthrough on a multi-RGB-D + IMU rig, see examples/multisensor/. For the full per-field API reference, see the C++ or Python docs.

Multisensor mode

Multisensor tracking is experimental: tracking may be inaccurate or fail for some sensor configurations and scenes. RGB-D cameras must use the pinhole model; cameras without depth support every distortion model.

Visual place recognition

Loop closure answers "have I drifted?" and, by default, needs a pose to search around. Visual place recognition answers "where am I?" from a single image and no pose at all. That is what a kidnapped robot needs: a robot switched on inside a map it has never localized in, or picked up mid-run and put down elsewhere, has no prior to search around.

Slam keeps a place recognition map alongside the pose graph: one frame per pose graph node, written into the SLAM map when it is saved. A match names a node rather than a stored pose, so the pose it reports follows loop closures and pose graph optimization instead of being the drifted one that was current when the frame was mapped. Resolving a kidnapping is LocalizeInMap's job: called without a guess pose, it takes candidate places from the saved map's place recognition map and verifies them against that map's landmarks, instead of searching a grid around a guess the robot does not have.

Place recognition runs AnyLoc, a VLAD aggregation of DINOv2 features, on the GPU. It needs a USE_TENSORRT build, which also makes its TensorRT engine (see models/anyloc). Both APIs expose it the same way:

Task	C++ (cuvslam::Slam)	Python (cuvslam.Slam)
Turn it on	Config::use_vpr = true and Config::vpr_model_path	Config(use_vpr=True, vpr_model_path=...)
Ask where a frame was taken	RecognizePlaceByFrame	recognize_place_by_frame
Save it with the SLAM map	SaveMap	save_map
Relocalize without a guess pose	LocalizeInMap with no guess_pose	localize_in_map(..., guess_pose=None)
Close loops from it	Config::loop_closure_mode = LoopClosureMode::VPR	Config(loop_closure_mode=LoopClosureMode.VPR)

doc/place_recognition.md walks through a mapping run and a relocalizing run, explains how it closes loops, and how to evaluate it with cuvslam_vpr_reporter.

Using cuVSLAM

The quickest way to get started is to install PyCuVSLAM from a pre-built wheel and explore the examples.

ROS2 Support

To use cuVSLAM in a ROS2 environment:

• Isaac ROS cuVSLAM GitHub
• Isaac ROS cuVSLAM Documentation
• Isaac ROS cuVSLAM User Manual

cuVSLAM Documentation

• cuVSLAM Technical Report
• PyCuVSLAM API Documentation
• cuVSLAM C++ API Documentation
• Version-matched offline API documentation is available as cuvslam-docs-<version>.tar.gz on the latest release. Extract it and open python/index.html or cpp/index.html.

Performance

cuVSLAM is a highly optimized visual tracking library validated across numerous public datasets and popular robotic camera setups. For detailed benchmarking and validation results, please refer to our technical report.

The accuracy and robustness of cuVSLAM can be influenced by several factors. If you experience performance issues, please check your system against these common causes:

• Hardware Overload: Hardware overload can negatively impact visual tracking, resulting in dropped frames or insufficient computational resources for cuVSLAM. Disable intensive visualization or image-saving operations to improve performance. For expected performance metrics on Jetson embedded platforms, see our technical report

• Intrinsic and Extrinsic Calibration: Accurate camera calibration is crucial. Ensure your calibration parameters are precise. For more details, refer to our guide on image undistortion. If you're new to calibration, consider working with experienced vendors

• Synchronization and Timestamps: Accurate synchronization significantly impacts cuVSLAM performance. Make sure multi-camera images are captured simultaneously—ideally through hardware synchronization—and verify correct relative timestamps across cameras. Refer to our multi-camera hardware assembly guide for building a rig with synchronized RealSense cameras

• Frame Rate: Frame rate significantly affects performance. The ideal frame rate depends on translational and rotational velocities. Typically, 30 FPS is suitable for most "human-speed" motions. Adjust accordingly for faster movements

• Resolution: Image resolution matters. VGA resolution or higher is recommended. cuVSLAM efficiently handles relatively high-resolution images due to CUDA acceleration

• Image Quality: Ensure good image quality by using suitable lenses, correct exposure, and proper white balance to avoid clipping large image regions. For significant distortion or external objects within the camera's field of view, please refer to our guide on static masking

• Motion Blur: Excessive motion blur can negatively impact tracking. Ensure that exposure times are short enough to minimize motion blur. If avoiding motion blur isn't feasible, consider increasing the frame rate or try the following or tracking modes

See Troubleshooting

Install PyCuVSLAM

PyCuVSLAM is the Python wrapper (bindings) for the cuVSLAM library.

Install from Wheels

Pre-built wheels are available on the cuVSLAM releases page for the following configurations:

Target	Ubuntu	Python wheel tag	Package	Architecture
Desktop/server	22.04	cp310 (Python 3.10)	cuvslam-cu12, cuvslam-cu13	x86_64
Desktop/server	24.04	cp312-abi3 (Python 3.12+)	cuvslam-cu12, cuvslam-cu13	x86_64
Jetson Orin	22.04 (JetPack 6.x)	cp310 (Python 3.10)	cuvslam-cu12	aarch64
Jetson Thor	24.04 (JetPack 7.x)	cp312-abi3 (Python 3.12+)	cuvslam-cu13	aarch64

Only the combinations listed above are provided as pre-built wheels. The cp312-abi3 wheels use Python's stable ABI and are compatible with Python 3.12 and later. Other Python, CUDA, or Jetson combinations require an installation from source.

Prerequisite: the wheels use cuBLAS, cuSOLVER and cuSPARSE from CUDA Toolkit 12 or 13, matching the package's cu12 or cu13 suffix. They come from either:

• a system CUDA Toolkit install, or
• NVIDIA's CUDA Toolkit wheels, installed with the cuda extra (x86_64 and Jetson Thor; Jetson Orin uses the CUDA Toolkit from JetPack). When installed, they take precedence over a system CUDA Toolkit, unless another module has already loaded these libraries.

Official wheels include cuNLS support for Multisensor mode; no separate cuNLS installation is required.

To install (virtual environment is recommended):

1. Go to the latest release.
2. Download the wheel matching the table above. On Jetson, also match the device family: Orin uses cu12/cp310; Thor uses cu13/cp312-abi3.
3. Install with pip:

pip install cuvslam_cu12-*.whl                         # with a system CUDA Toolkit
pip install "./cuvslam_cu12-<version>-<tags>.whl[cuda]" # with CUDA Toolkit wheels from PyPI

Install only one of cuvslam-cu12 and cuvslam-cu13 in an environment: both provide the cuvslam module, and import cuvslam warns if more than one cuVSLAM package is installed.

If a pre-built wheel is not available for your system, see Install from Source below.

Install from Source

Note: cuVSLAM must be built before installing from source.

To install PyCuVSLAM from repository (virtual environment is recommended):

CUVSLAM_BUILD_DIR=<path-to-cuvslam-build> pip install python/

CUVSLAM_BUILD_DIR is required for build script to find libcuvslam.so. Warning: Due to scikit-build-core limitations, bindings must be reinstalled after rebuilding libcuvslam.

Build cuVSLAM

Pre-built Libraries

Pre-built C++ SDK archives are available on the latest release:

Target	Ubuntu	CUDA	Archive slug
Desktop/server	22.04 or 24.04	12.6.3 or 13.2.0	x86_64-cuda<version>-ubuntu<version>
Jetson Orin	22.04 (JetPack 6.x)	12.6.3	orin-cuda12.6.3-ubuntu22.04
Jetson Thor	24.04 (JetPack 7.x)	13.0.1	thor-cuda13.0.1-ubuntu24.04

The desktop/server row represents four archives covering both Ubuntu versions with both listed CUDA versions. Select the archive matching your target, Ubuntu version, and CUDA version. Each archive contains bin/libcuvslam.so, bin/cuvslam_api_launcher, and the public headers under include/cuvslam/.

For Python usage, pre-built wheels are the recommended approach.

Building from Source

Requirements

• Ubuntu 22+ (22.04 & 24.04 tested) x86_64/aarch64 (Desktop/Laptop & Nvidia Jetson Orin/Thor)
• CUDA Toolkit 12.6 or later for the default USE_CUNLS=ON build, Jetpack 6.1/6.2/7.0/7.1
  • Older CUDA 12 versions require configuring with -DUSE_CUNLS=OFF (see cuNLS).
• apt update && apt install g++ cmake git git-lfs python3-dev
  • git + git-lfs to clone this repository
  • CMake 3.19+, gcc
  • Python 3.9+ (for python bindings, examples and some tools)

Build on local x86

In the repository root build C++ code using one of two ways:

1. Build manually:

cmake -S . -B build
cmake --build build --parallel $(nproc)

With CMake 4.x, add -DCMAKE_POLICY_VERSION_MINIMUM=3.5 during configure if an external dependency reports that compatibility with CMake < 3.5 has been removed:

cmake -S . -B build -DCMAKE_POLICY_VERSION_MINIMUM=3.5

2. Set source & build paths for build_release.sh and run it.

   Important: Before running build_release.sh set paths using one of the options:

   1. Set paths in ~/.bashrc (or equivalent shell login script), which will be useful when switching between cuvslam branches:

      export CUVSLAM_SRC_DIR=<path-to-cuvslam-src>
      export CUVSLAM_DST_DIR=<path-to-cuvslam-build>
      

   2. Update SRC & DST paths in build_release.sh

CMake options

All flags have defaults; override with -DFLAG=VALUE.

Flag	Default	Purpose
USE_CUDA	ON	CUDA acceleration
USE_CUNLS	ON	cuNLS (CUDA nonlinear least squares); requires USE_CUDA
USE_LMDB	ON	LMDB map database
USE_RERUN	OFF	Rerun SDK visualization
USE_NVTX	OFF	NVIDIA NVTX profiling
USE_TENSORRT	OFF	AnyLoc place recognition backend; requires USE_CUDA and TensorRT 8.6+
CUVSLAM_BUILD_ANYLOC_ENGINE	ON with USE_TENSORRT	builds AnyLoc's TensorRT engine: an ONNX export in a Python venv, then a TensorRT build (needs network access); see models/anyloc

Build types: Release (default), Debug, RelWithDebInfo, MinSizeRel. Do not mix types in the same build directory.

cuNLS

cuNLS (CUDA nonlinear least squares) is enabled by default (USE_CUNLS=ON) and is built from source via FetchContent, like the other external dependencies — no separate install or path is required. The source is pinned in cmake/ext/cunls.cmake, and spdlog is shared with cuVSLAM. cuVSLAM uses cuNLS's DenseQR solver and builds with the optional cuDSS backend disabled, so no cuDSS archive, library, or runtime package is required. A network connection and CUDA Toolkit 12.6 or later are required for the default USE_CUNLS=ON build. The resulting static cuNLS archive is bundled into libcuvslam.

cuNLS source and license information are published in the nvidia-isaac/cuNLS repository. Release wheels and C++ packages built with the default configuration include cuNLS support and do not require a separate runtime package.

cuNLS requires USE_CUDA=ON. To build from source with older CUDA versions, configure with -DUSE_CUNLS=OFF. This disables cuNLS and the Multisensor odometry mode that depends on it.

Build on Jetson (aarch64)

JetPack only ships CUDA runtime libraries by default. Install the dev packages on the Jetson before building:

# JetPack 6.x (CUDA 12)
sudo apt-get install libcublas-dev-12-6 libcusolver-dev-12-6
# JetPack 7.x (CUDA 13)
sudo apt-get install libcublas-dev-13-0 libcusolver-dev-13-0

For building natively, follow the same steps as Build on local x86. For building remotely via SSH:

./copy_to_remote.sh <jetson-host>
ssh <jetson-host> 'export CUVSLAM_SRC_DIR=~/cuvslam/src CUVSLAM_DST_DIR=~/cuvslam/build && ~/cuvslam/src/build_release.sh [options]'
./copy_from_remote.sh <jetson-host>

To speed up the build, target your specific GPU architecture instead of building for all, e.g.:

./build_release.sh --cuda_arch=87   # 87 for Orin Nano/NX/AGX

Omit --cuda_arch to build for all architectures (default). To detect your GPU's SM version:

nvidia-smi --query-gpu=compute_cap --format=csv,noheader   # e.g. 8.7 -> use 87

Enable rerun visualizer for C++ code

1. Create virtual environment and install rerun SDK:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install rerun-sdk==0.33.1
   

2. Specify virtual env with CUVSLAM_TOOLS_PYENV environment variable (defaults to .venv in repository root).
3. Update build_release.sh and set USE_RERUN to ON
4. Run any tool from tools folder

C++ unit tests disable Rerun by default, even in builds configured with USE_RERUN=ON. To enable the viewer for interactive test debugging, ensure rerun is on PATH and set RERUN=1:

cd <build-dir>
RERUN=1 ctest --output-on-failure

FAQ

Q: What Python versions are supported by PyCuVSLAM?

A: Pre-built wheels use cp310 for Python 3.10 on Ubuntu 22.04 and cp312-abi3 for Python 3.12 or later on Ubuntu 24.04. Jetson wheels are limited to Orin with cu12/cp310 and Thor with cu13/cp312-abi3; see the wheel table. When built from source, PyCuVSLAM supports Python 3.9 and later.

Troubleshooting

See TROUBLESHOOTING.md

Feedback

Are you having problems running cuVSLAM or PyCuVSLAM? Do you have any suggestions? We'd love to hear your feedback in the issues tab.

License

This project is licensed under the NVIDIA Community License, for details refer to the LICENSE file.

Citation

If you find this work useful in your research, please consider citing:

@article{korovko2025cuvslam,
      title={cuVSLAM: CUDA accelerated visual odometry and mapping},
      author={Alexander Korovko and Dmitry Slepichev and Alexander Efitorov and Aigul Dzhumamuratova and Viktor Kuznetsov and Hesam Rabeti and Joydeep Biswas and Soha Pouya},
      year={2025},
      eprint={2506.04359},
      archivePrefix={arXiv},
      primaryClass={cs.RO},
      url={https://arxiv.org/abs/2506.04359},
}