Implementation:NVIDIA DALI Plugin Manager Load Library

Knowledge Sources	NVIDIA DALI
Domains	Custom_Operators, Plugin_Architecture, Dynamic_Loading
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete PluginManager::LoadLibrary() method and nvidia.dali.plugin_manager.load_library() Python wrapper provided by NVIDIA DALI for dynamically loading custom operator shared libraries into the DALI runtime at execution time.

Description

The PluginManager::LoadLibrary() method (defined in dali/plugin/plugin_manager.cc) is the core C++ function for dynamic plugin loading. It:

1. Accepts a lib_path string, a global_symbols boolean, and an allow_fail boolean.
2. Computes dlopen flags: RTLD_GLOBAL or RTLD_LOCAL based on global_symbols, combined with RTLD_LAZY.
3. Calls dlopen(lib_path.c_str(), flags) to load the shared library.
4. If dlopen returns nullptr, constructs an error message using dlerror() and either logs it (if allow_fail is true) or raises a DALI_FAIL exception.

The Python-side entry point is nvidia.dali.plugin_manager.load_library(path), which calls through to this C++ method. After loading, the operator's static initializers have registered it in the schema and factory registries, making it available as fn.operator_name() in pipeline definitions.

The PluginManager class also provides:

• LoadDirectory(): Recursively scans a directory for files matching libdali_*.so and loads each one.
• LoadDefaultPlugins(): Loads plugins from the default plugin directory or from paths specified by the DALI_PRELOAD_PLUGINS environment variable.

Usage

Call load_library() at the top of your script, before defining any pipeline that uses the custom operator.

Code Reference

Source Location

• Repository: NVIDIA DALI
• File (C++): dali/plugin/plugin_manager.cc (lines 26-41)
• File (Python usage): docs/examples/custom_operations/custom_operator/naive_histogram/test_naive_histogram.py (lines 21-23)

Signature

// C++ API
void PluginManager::LoadLibrary(const std::string& lib_path,
                                 bool global_symbols = false,
                                 bool allow_fail = false);

# Python API
nvidia.dali.plugin_manager.load_library(library_path: str) -> None

Import

import nvidia.dali.plugin_manager as plugin_manager

#include "dali/plugin/plugin_manager.h"

I/O Contract

Inputs

Name	Type	Required	Description
library_path / lib_path	str / const std::string &	Yes	Absolute or relative path to the shared library file (.so) containing the custom operator.
global_symbols	bool	No (default: false)	If true, loads with RTLD_GLOBAL so the library's symbols are available to subsequently loaded libraries. Default is RTLD_LOCAL.
allow_fail	bool	No (default: false)	If true, a failed load prints a warning instead of raising an exception.

Outputs

Name	Type	Description
Side effect: Schema registration	Global SchemaRegistry	The loaded library's DALI_SCHEMA static initializers register the operator's schema, making it discoverable by name.
Side effect: Factory registration	Device-specific OperatorRegistry	The loaded library's DALI_REGISTER_OPERATOR static initializers register factory functions, enabling operator instantiation.
Side effect: Python API	nvidia.dali.fn namespace	The operator becomes available as fn.operator_name() for use in pipeline definitions.

Usage Examples

Example: Loading a custom operator plugin and using it in a pipeline

import nvidia.dali.plugin_manager as plugin_manager
from nvidia.dali import pipeline_def
from nvidia.dali.types import DALIImageType
import nvidia.dali.fn as fn

# Load the custom operator shared library
plugin_manager.load_library("./build/libnaivehistogram.so")

@pipeline_def
def naive_hist_pipe():
    img, _ = fn.readers.file(files=test_file_list)
    img = fn.decoders.image(img, device="mixed", output_type=DALIImageType.GRAY)
    img = img.gpu()
    # Use the custom operator just like a built-in operator
    img = fn.naive_histogram(img, n_bins=24)
    return img

Example: C++ LoadLibrary implementation

void PluginManager::LoadLibrary(const std::string& lib_path,
                                 bool global_symbols, bool allow_fail) {
  int flags = global_symbols ? RTLD_GLOBAL : RTLD_LOCAL;
  flags |= RTLD_LAZY;
  LOG_LINE << "Loading " << lib_path << "\n";
  auto handle = dlopen(lib_path.c_str(), flags);
  if (handle == nullptr) {
    std::string err_msg =
        std::string("Failed to load library ") + lib_path + ": " + std::string(dlerror());
    if (allow_fail) {
      std::cerr << err_msg << "\n";
    } else {
      DALI_FAIL(err_msg);
    }
  }
}

Related Pages

Implements Principle

• Principle:NVIDIA_DALI_Plugin_Loading

Requires Environment

• Environment:NVIDIA_DALI_CMake_Build_Environment