Using a Custom USD Build with FnUsdShim

In order to use a custom USD version with Nuke, it is now required to build the libFnUsdShim library against your custom USD version.

The source code for libFnUsdShim is provided with Nuke in the source/FnUsdShim directory next to the Nuke executable.

This guide explains how to build and configure FnUsdShim to work with a custom USD (Universal Scene Description) build, and how to set up your environment for use with Nuke.

Contents

  1. Building FnUsdShim against a custom USD build

    1.1 Dependencies required 1.2 Build instructions

  2. Setting up the environment to use the custom USD build with Nuke

    2.1 Environment variables to set 2.2 Instructions for different operating systems

  3. Running Nuke as a Python module with the custom USD build

    3.1 Setting the USG_PLUGINS_PATH environment variable

1. Building FnUsdShim Against a Custom USD Build

1.1 Dependencies Required

  • USD built with the following features enabled:

    • usd-imaging

    • python

  • The same Python version as used by Nuke.

  • CMake (with Ninja recommended).

  • Required CMake arguments:

    • FdkBase_DIR: Path to FdkBaseConfig.cmake (from Nuke install).

    • FnUsdAbstraction_DIR: Path to FnUsdAbstractionConfig.cmake (from Nuke install).

    • OpenSubdiv_DIR: Path to OpenSubdiv (often same as pxr_DIR).

    • pxr_DIR: Path to the root of your custom USD installation.

    • CMAKE_INSTALL_PREFIX: Where to install FnUsdShim.

1.2 Build Instructions

mkdir build && cd build
cmake .. -G Ninja \
  -Dpxr_DIR=<path to USD> \
  -DFdkBase_DIR=<path to Nuke installation>/cmake/ \
  -DFnUsdAbstraction_DIR=<path to Nuke installation>/cmake/ \
  -DCMAKE_INSTALL_PREFIX=./install
cmake --build . --config Release

For Windows, use ^ for line continuation and adjust paths accordingly.

2. Setting Up the Environment to Use the Custom USD Build

2.1 Environment Variables to Set

  • NUKE_USD_PYTHON_PATH_DISABLED=1: Disables Nuke’s built-in USD Python path.

  • PYTHONPATH: Add <path to USD>/lib/python.

  • USG_SHIMLIB_NAME: Full path to your built FnUsdShim plugin (e.g., /path/to/libFnUsdShim-USD-25.08.so).

  • USG_SHIMLIB_PATH: (Optional) Colon- or semicolon-separated list of directories to search for FnUsdShim.

  • USG_USD_LIB_PATH: Path to USD lib directory.

  • USG_USD_PLUGIN_PATH: Path to USD plugin directory (e.g., plugin/usd).

2.2 Instructions for Different Operating Systems

Linux/macOS:

export NUKE_USD_PYTHON_PATH_DISABLED=1
export PYTHONPATH=$PYTHONPATH:<path to USD>/lib/python
export USG_SHIMLIB_NAME=<full path to FnUsdShim plugin>
export USG_USD_LIB_PATH=<path to USD>/lib
export USG_USD_PLUGIN_PATH=<path to USD>/plugin/usd

Windows (cmd):

set NUKE_USD_PYTHON_PATH_DISABLED=1
set PYTHONPATH=%PYTHONPATH%;<path to USD>\lib\python
set USG_SHIMLIB_NAME=<full path to FnUsdShim plugin>
set USG_USD_LIB_PATH=<path to USD>\lib
set USG_USD_PLUGIN_PATH=<path to USD>\plugin\usd

3. Running Nuke as a Python Module with the Custom USD Build

If you are importing Nuke as a Python module (import nuke) from an external Python session, you must ensure that the Nuke USD plugins can be found. By default, Nuke will load them from within a FnUsdAbstraction directory next to the executable.

3.1 Setting the USG_PLUGINS_PATH Environment Variable

Set the USG_PLUGINS_PATH environment variable to point to the Nuke USD plugins directory.

Example (Windows):

set USG_PLUGINS_PATH=<path to Nuke installation>\FnUsdAbstraction\resources

Example (Linux/macOS):

export USG_PLUGINS_PATH=<path to Nuke installation>/FnUsdAbstraction/resources

Additional Notes

  • You can also configure FnUsdShim discovery using a .FnUsdShim file in your .nuke directory. The first line is the plugin filename, the second line is a path list (colon- or semicolon-separated).

  • For debugging, set USG_DEBUG_USDSHIMLIB=1 to print plugin loading information.

  • On Windows, ensure all required DLL directories are on PATH or use usg_LIB_DIRS for Python 3.8+.