Is this page helpful?

[isaacsim.storage.native] Isaac Sim Native Storage#

Version: 1.9.2

Overview#

isaacsim.storage.native provides utilities for accessing Isaac Sim assets from Nucleus servers or S3 buckets. This extension handles asset path resolution, server connectivity checks, file system operations, and USD reference validation across both local and remote storage systems. It enables Isaac Sim to seamlessly work with assets stored on various backends while providing robust error handling and retry mechanisms for network operations.

Concepts#

Asset Root Discovery#

The extension automatically discovers and validates Isaac Sim asset root paths on connected Nucleus servers. It uses configurable retry logic with exponential backoff to handle transient network failures when checking server connectivity.

Path Resolution#

The extension provides intelligent path resolution that handles both local filesystem paths and Omniverse URLs. When an asset cannot be found at its original location, the system automatically attempts to resolve it relative to the configured Isaac Sim assets root path.

Version Management#

Asset versions are tracked using semantic versioning with the Version class. The extension can verify asset compatibility by reading version.txt files from asset root paths and comparing them against the current Isaac Sim application version.

Functionality#

Server Operations#

Server discovery and validation through build_server_list, check_server, and get_server_path functions. These operations support both synchronous and asynchronous execution patterns, with the async versions providing retry logic for improved reliability.

Asset downloading from S3 buckets to Nucleus servers using download_assets_async with configurable concurrency limits and progress tracking.

Folder management with create_folder and delete_folder operations for organizing assets on Nucleus servers.

File System Operations#

Path utilities including path_join, path_relative, and path_dirname that work consistently across local paths and Omniverse URLs. The is_local_path function distinguishes between offline and online resources.

File discovery with find_files_recursive and find_filtered_files supporting regex pattern matching, depth limiting, and exclusion filters. These functions can traverse both local directories and remote Nucleus paths.

File validation through is_file, is_dir, is_valid_usd_file, and is_mdl_file functions that work across different storage backends.

USD Reference Management#

Reference analysis with get_stage_references to extract all references from USD stages, and find_external_references to identify references pointing outside a base path.

Missing reference detection through find_missing_references, layer_has_missing_references, and prim_has_missing_references functions that recursively validate USD file dependencies.

Reference counting via count_asset_references to analyze asset usage patterns across USD files.

Integration#

The extension integrates with omni.client for Omniverse operations and isaacsim.core.version for version compatibility checks. It provides both synchronous and asynchronous APIs to accommodate different usage patterns within Isaac Sim applications.

Authentication for Nucleus servers is handled automatically when the ETM_ACTIVE environment variable is set, enabling seamless access to protected asset repositories.

Enable Extension#

The extension can be enabled (if not already) in one of the following ways:

Define the next entry as an application argument from a terminal.

APP_SCRIPT.(sh|bat) --enable isaacsim.storage.native

Define the next entry under [dependencies] in an experience (.kit) file or an extension configuration (extension.toml) file.

[dependencies]
"isaacsim.storage.native" = {}

Open the Window > Extensions menu in a running application instance and search for isaacsim.storage.native. Then, toggle the enable control button if it is not already active.

Extension: {{ extension_version }}

Documentation Generated: Jun 05, 2026

Settings#

Settings Provided by the Extension#

persistent.isaac.asset_root.default#

  • Default Value: “https://omniverse-content-production.s3-us-west-2.amazonaws.com/Assets/Isaac/6.0”

  • Description: Default asset root path for Isaac Sim.

Resolution order (highest to lowest priority):

Priority

Source

Example

1

ISAACSIM_ASSET_ROOT environment variable

export ISAACSIM_ASSET_ROOT=https://my-server

2

Command-line argument

--/persistent/isaac/asset_root/default=https://my-server

3

Experience (.kit) file

persistent.isaac.asset_root.default = "https://my-server"

4

Extension default (extension.toml)

persistent.isaac.asset_root.default = "https://omniverse-content-production.s3-us-west-2.amazonaws.com/Assets/Isaac/6.0"

At startup the extension reads the ISAACSIM_ASSET_ROOT environment variable and, if set, overwrites the setting regardless of any value provided by a .kit file or command-line argument. When the variable is unset, the normal Kit settings precedence applies (CLI > .kit > extension.toml).

persistent.isaac.asset_root.timeout#

  • Default Value: 5.0

  • Description: Timeout in seconds for asset root path to be resolved.

persistent.isaac.asset_root.retry_attempts#

  • Default Value: 3

  • Description: Number of retries for transient asset root connectivity checks.

persistent.isaac.asset_root.retry_base_delay#

  • Default Value: 0.5

  • Description: Initial retry delay in seconds using exponential backoff.

Python API#

Nucleus server utilities for Isaac Sim asset storage and management operations.

class Version(s: str)#

Bases: Version

Semantic version representation for comparing Isaac Sim assets versions.

A named tuple that parses and stores version strings in the format “major.minor.patch”. Supports comparison operations inherited from the namedtuple base class.

Example:

>>> from isaacsim.storage.native.nucleus import Version
>>>
>>> v1 = Version("1.2.3")
>>> v1.major, v1.minor, v1.patch
(1, 2, 3)
>>> str(v1)
'1.2.3'

Create a new Version instance from a version string.

Parameters:

s – Version string in the format “major.minor.patch” (e.g., “1.2.3”).

Returns:

A new Version named tuple with major, minor, and patch components.

build_server_list() → list#

Return list with all known servers to check.

Retrieves the list of mounted Nucleus server drives from the persistent settings.

Returns:

List of servers found.

check_server(server: str, path: str, timeout: float = 10.0) → bool#

Check a specific server for a path.

Parameters:

  • server – Name of Nucleus server.

  • path – Path to search.

  • timeout – Timeout in seconds.

Returns:

True if folder is found.

async check_server_async(
server: str,
path: str,
timeout: float = 10.0,
) → bool#

Check a specific server for a path.

This function retries transient failures using exponential backoff. It retries when the stat operation times out or returns omni.client.Result.ERROR_CONNECTION. Retry behavior is controlled by: /persistent/isaac/asset_root/retry_attempts and /persistent/isaac/asset_root/retry_base_delay.

Parameters:

  • server – Name of Nucleus server.

  • path – Path to search.

  • timeout – Per-attempt timeout in seconds.

Returns:

True if folder is found, False otherwise.

create_folder(server: str, path: str) → bool#

Create a folder on server.

Parameters:

  • server – Name of Nucleus server.

  • path – Path to folder.

Returns:

True if folder is created successfully.

delete_folder(server: str, path: str) → bool#

Remove folder and all of its contents.

Parameters:

  • server – Name of Nucleus server.

  • path – Path to folder.

Returns:

True if folder is deleted successfully.

async download_assets_async(
src: str,
dst: str,
progress_callback: object,
concurrency: int = 10,
copy_behaviour: omni.client.CopyBehavior = omni.client.CopyBehavior.OVERWRITE,
copy_after_delete: bool = True,
timeout: float = 300.0,
) → omni.client.Result#

Download assets from S3 bucket.

Parameters:

  • src – URL of S3 bucket as source.

  • dst – URL of Nucleus server to copy assets to.

  • progress_callback – Callback function to keep track of progress of copy. The callback receives two arguments: current count and total count.

  • concurrency – Number of concurrent copy operations.

  • copy_behaviour – Behavior if the destination exists.

  • copy_after_delete – True if destination needs to be deleted before a copy.

  • timeout – Timeout in seconds for each copy operation.

Returns:

Result of the copy operation.

find_nucleus_server(suffix: str) → tuple[bool, str]#

Attempts to determine best Nucleus server to use based on existing mountedDrives setting.

Deprecated since version This: function is deprecated. Use get_assets_root_path() instead.

Parameters:

suffix – Path to folder to search for.

Returns:

Tuple of (found, url) where found is True if Nucleus server with suffix is found and url is the URL of the found Nucleus server.

get_assets_root_path(*, skip_check: bool = False) → str#

Tries to find the root path to the Isaac Sim assets on a Nucleus server.

Parameters:

skip_check – If True, skip the checking step to verify that the resolved path exists.

Raises:

  • RuntimeError – If the root path setting is not set.

  • RuntimeError – If the root path is not found.

Returns:

URL of Nucleus server with root path to assets folder.

async get_assets_root_path_async(*, skip_check: bool = False) → str#

Tries to find the root path to the Isaac Sim assets on a Nucleus server.

Parameters:

skip_check – If True, skip the checking step to verify that the resolved path exists.

Raises:

  • RuntimeError – If the root path setting is not set.

  • RuntimeError – If the root path is not found.

Returns:

URL of Nucleus server with root path to assets folder.

get_assets_server() → str | None#

Tries to find a server with the Isaac Sim assets.

Deprecated since version This: function is deprecated. Use get_server_path() instead.

Returns:

None. This function is deprecated and always returns None.

get_full_asset_path(path: str) → str | None#

Tries to find the full asset path on connected servers.

Searches for the asset path first in the default asset root, then in all mounted Nucleus drives.

Parameters:

path – Path of asset from root to verify.

Raises:

RuntimeError – If the root path is not found.

Returns:

URL or full path to assets, or None if assets not found.

async get_full_asset_path_async(path: str) → str | None#

Tries to find the full asset path on connected servers (asynchronous version).

Searches for the asset path first in the default asset root, then in all mounted Nucleus drives.

Parameters:

path – Path of asset from root to verify.

Raises:

RuntimeError – If the root path is not found.

Returns:

URL or full path to assets, or None if assets not found.

get_isaac_asset_root_path() → str | None#

Get the Isaac Sim asset root path.

Deprecated since version This: function is deprecated. Use get_assets_root_path() instead.

Returns:

None. This function is deprecated and always returns None.

get_nvidia_asset_root_path() → str | None#

Get the NVIDIA asset root path.

Deprecated since version This: function is deprecated. Use get_assets_root_path() instead.

Returns:

None. This function is deprecated and always returns None.

get_server_path(suffix: str = '') → str | None#

Tries to find a Nucleus server with specific path.

Parameters:

suffix – Path to folder to search for.

Raises:

RuntimeError – If the root path is not found.

Returns:

URL of Nucleus server with path to folder, or None if not found.

async get_server_path_async(suffix: str = '') → str | None#

Tries to find a Nucleus server with specific path (asynchronous version).

Parameters:

suffix – Path to folder to search for.

Raises:

RuntimeError – If the root path is not found.

Returns:

URL of Nucleus server with path to folder, or None if not found.

get_url_root(url: str) → str#

Get root from URL or path.

Extracts the server root (protocol and netloc) from a full URL.

Parameters:

url – Full http or omniverse path.

Raises:

RuntimeError – If the root path is not found or protocol is unsupported.

Returns:

Root path or URL of the Nucleus server.

Example:

>>> from isaacsim.storage.native import get_url_root
>>>
>>> get_url_root("omniverse://localhost/NVIDIA/Assets")
'omniverse://localhost'
>>> get_url_root("https://example.com/path/to/asset")
'https://example.com'
is_dir(path: str) → bool#

Check if path is a folder.

Parameters:

path – Path to folder.

Returns:

True if path is a folder.

Raises:

Exception – If failed to determine if the path is a folder.

async is_dir_async(path: str) → bool#

Check if path is a folder.

Parameters:

path – Path to folder.

Returns:

True if path is a folder.

Raises:

Exception – If failed to determine if the path is a folder.

is_file(path: str) → bool#

Check if path is a file.

Parameters:

path – Path to file.

Returns:

True if path is a file.

Raises:

Exception – If failed to determine if the path is a file.

async is_file_async(path: str) → bool#

Check if path is a file.

Parameters:

path – Path to file.

Returns:

True if path is a file.

Raises:

Exception – If failed to determine if the path is a file.

async list_folder(path: str) → tuple[list, list]#

List files and sub-folders from root path.

Parameters:

path – Path to root folder.

Returns:

Tuple containing list of file paths and list of sub-folder paths.

Raises:

Exception – When unable to find files under the path.

async recursive_list_folder(path: str) → list#

Recursively list all files.

Parameters:

path – Path to folder.

Returns:

List of paths to each file.

verify_asset_root_path(path: str) → tuple[omni.client.Result, str]#

Attempts to determine Isaac assets version and check if there are updates.

Reads the version.txt file from the asset root path and compares it against the current Isaac Sim application version to verify compatibility.

Parameters:

path – URL or path of asset root to verify.

Returns:

Tuple containing the result (OK if assets verified) and the version string of the Isaac Sim assets.