OpenVDB: a sparse volume library from DreamWorks, and how to build it

What OpenVDB actually stores, and who needs that

The README describes OpenVDB as a C++ library comprising a hierarchical data structure and a suite of tools for the efficient storage and manipulation of sparse volumetric data discretized on three-dimensional grids. The operative word is sparse. A dense 3D grid at film resolution allocates memory for every voxel whether or not anything is there. OpenVDB's hierarchical structure only pays for the regions that hold values, which is why it was developed at DreamWorks Animation for volumetric work in feature film production: smoke, fire, clouds, water and explosions are mostly empty space with detail concentrated in a few places.

The audience is narrow and specific. It is a library, not an application. You write C++ against it, or you use the Python bindings, or you consume it through a host application that has already integrated it. If your work is writing a solver, a renderer, a simulation cache format, or a tool that has to read and write volumetric grids at scale, the data structure is the point. If your work is opening a .vdb file to look at it, you are not the target user and the repository does not ship a general-purpose viewer.

The tree underneath, and why NanoVDB exists separately

The repository layout tells you how the project is split. The openvdb/ directory holds the core library. openvdb_ax/ is OpenVDB AX, a separate component that the README says depends on the core library. nanovdb/ is NanoVDB, which the README notes can be built with and without OpenVDB support, and which has its own build instructions. openvdb_cmd/ holds executables, and openvdb_houdini/, openvdb_maya/ and openvdb_wolfram/ are integrations for those hosts.

That split is the most important architectural fact for a new user. OpenVDB proper is a CPU library that leans on TBB for threading and Blosc for compression. NanoVDB is a different representation aimed at GPU access, and the pyproject.toml in the repository configures it with NANOVDB_USE_CUDA="ON" alongside NANOVDB_USE_OPENVDB="ON". They are not interchangeable. If you search for a comparison between them, the practical distinction is that one is the full library with its tools and file format, and the other is a compact structure meant to be read on hardware where you cannot afford the full traversal. The documentation, not this article, is where the details of that boundary live.

One more structural note: the README states plainly that this GitHub repository hosts the trunk of development, that it is the newest public version with the latest features and bug fixes, and that it has not undergone a lot of testing and is generally less stable than the production releases. That is an unusually direct warning and it should shape how you pin your dependency.

Installing OpenVDB and building a first grid in Python

The README gives a Developer Quick Start for the core library. On Linux, dependencies come from the distribution's package manager; the README lists Boost iostreams, TBB and Blosc, and notes that if your distribution does not have required versions you should consider apt pinning. On macOS the same three come from Homebrew.

apt-get install -y libboost-iostreams-dev
apt-get install -y libtbb-dev
apt-get install -y libblosc-dev

After the dependencies, the clone and build sequence is the one the README prints. It creates a build directory, configures with cmake and builds with make. Expect a C++ compile of a large codebase; the README's own example uses make -j4.

git clone git@github.com:AcademySoftwareFoundation/openvdb.git
cd openvdb
mkdir build
cd build
cmake ..
make -j4 && make install

Optional components are enabled by passing variables to the cmake configure step. The README documents three of them in a table, and says the build documentation has a complete list.

cmake -D OPENVDB_BUILD_AX=ON -D OPENVDB_BUILD_NANOVDB=ON -D NANOVDB_USE_OPENVDB=ON ..

On Windows the README recommends setting VCPKG_DEFAULT_TRIPLET to x64-windows, requires Visual Studio and CMake, and gives a vcpkg install line for zlib, blosc, tbb, boost-iostreams and boost-interprocess, followed by a cmake configure that points CMAKE_TOOLCHAIN_FILE at the vcpkg toolchain and sets VCPKG_TARGET_TRIPLET to x64-windows.

vcpkg install zlib:x64-windows
vcpkg install blosc:x64-windows
vcpkg install tbb:x64-windows
vcpkg install boost-iostreams:x64-windows
vcpkg install boost-interprocess:x64-windows

The Python bindings are a separate path. The repository's pyproject.toml declares the project name as openvdb, requires Python 3.10 or newer, depends on numpy, and builds through scikit_build_core with nanobind. It turns on the Python module and NanoVDB's Python module through CMake defines. Because the build backend is scikit-build-core, the package is built from source against the C++ library rather than being a pure-Python wheel, so a working compiler and the dependencies above are still part of the picture. The README does not print a pip command for it, so treat the build documentation as the authority on that step.

Where OpenVDB is the wrong choice

The most common mismatch is expecting an application. The README lists a website, a discussion forum, Doxygen documentation, releases, a license and a Slack workspace. It does not describe a viewer or an editor. If your goal is to look inside a .vdb file, OpenVDB will not do it for you; the ecosystem around the format is where that happens, and the repository is not that.

The second mismatch is dense data. The hierarchical structure is designed for sparsity. If your volume is fully occupied, you are paying the traversal and bookkeeping cost of a tree without collecting the memory saving that justifies it, and a flat array will be simpler to write against.

The third is build weight. This is a CMake C++ project with Boost, TBB and Blosc among its dependencies, plus optional CUDA for NanoVDB. That is a real cost in CI, in cross-compilation, and in packaging. A project that only needs a small amount of volumetric math should think hard before taking it on.

Finally, there is a stability caveat the README states itself: the trunk is less tested than the production releases. If you build from master you are opting into that, and the project says so in advance.

How it compares with a general mesh or point representation

The honest alternative for many teams is not another volume library but a different data model entirely. A mesh or a point cloud stores surfaces and samples; OpenVDB stores a discretized field over a 3D grid, which is what you need when the quantity you care about varies continuously through space rather than sitting on a boundary. Smoke density, temperature, velocity and signed distance fields are field quantities. A triangle mesh is a poor container for them because it has no interior.

Within the volume world, the meaningful comparison is OpenVDB against NanoVDB, and they live in the same repository. The README's own framing is that NanoVDB can be built with and without OpenVDB support, and the pyproject.toml enables NanoVDB alongside the core library with CUDA on. The difference in approach is the representation and where it is meant to run: the full library carries the tools and the file format, while NanoVDB is the variant configured for GPU use. Choosing between them is a question about your execution target, not about which project is better.

Licence, release cadence and what upgrading costs

OpenVDB is released under the Apache License, Version 2.0. The README notes that the project completed a re-licensing from Mozilla Public License Version 2.0 to Apache 2.0, and points to RE-LICENSE_NOTE.txt at the repository root for details. For anyone auditing dependencies, that history is worth reading rather than assuming, and the note that contributor trademarks may not be used in association with the project without express permission is a separate constraint from the code licence. This is not legal advice; read the licence text and the re-license note yourself.

The release history shows a steady line: v12.1.0 in August 2025, v12.1.1 in September 2025, and v13.0.0 on 2025-11-04, which is also the date of the most recent push to the repository. A major version bump is the signal that matters for upgrade planning, because it is where API and build changes land. The pyproject.toml still declares version 12.0.1, which is a reminder that the Python packaging metadata and the C++ release tags do not always move together, so check both when you pin.

The repository carries a pendingchanges/ directory alongside CHANGES, and a CONTRIBUTING.md with contribution guidelines. For a team tracking upgrades, CHANGES and the release notes are the places to read before moving a major version, and the trunk warning in the README is the reason to build against a tagged release in production.

Editorial conclusion

Adopt OpenVDB if you are writing C++ or Python that has to store and process sparse 3D grids, particularly in a VFX or simulation pipeline, and you can absorb a CMake build with Boost, TBB and Blosc. Do not adopt it if you only need to view a .vdb file, or if your data is dense and fits in a flat array. Before committing, check the production releases page rather than the trunk, since the README states this repository is the newest public version and is generally less stable than the tagged releases, and confirm the Python wheel builds against the Python version you target, since pyproject.toml requires 3.10 or newer.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes