Skip to main content

simready-retrieve

Download a SimReady asset from cloud storage and get back the local path to its main USD file. Retrieve can also convert the asset to a target profile and validate the result before it hands the path back.

A workflow guide, a full CLI reference, and a full Python API reference ship inside the package, under docs/.

Installation

Retrieve needs Python 3.12 or newer. On an older interpreter, pip refuses to resolve it.

pip install simready-retrieve

Internal builds are published to the NVIDIA artifactory, so append --extra-index-url https://artifactory.nvidia.com/artifactory/api/pypi/ct-omniverse-pypi-local/simple.

To convert an asset to a profile, also install the tier package that defines that profile, such as simready-foundation-tier-core. Retrieve resolves profiles from the tiers you have installed.

This wheel also ships simready-derive: the simready.derive module and the simready-derive command. Derive is not released on its own. If you already have a standalone simready-derive wheel, uninstall it first, because both install the same files.

Asset URIs

Retrieve picks the storage backend from the URI scheme. You never choose one.

URI Storage
hf://<org>/<repo>/<asset>[@<commit>] Hugging Face
https://huggingface.co/datasets/<org>/<repo>/... Hugging Face
omniverse://<host>/<folder-or-usd> Nucleus
omniverse://<host>/assets/by-name/<name> OmniStorage
s3://<bucket>/<prefix> Public S3 bucket

omni:// works anywhere omniverse:// does. An AWS S3 HTTPS URL works anywhere s3:// does. Nucleus and OmniStorage need omni.client, which is installed for you. OmniStorage also needs SIMREADY_OMNI_DISCOVERY_URL set to your discovery endpoint.

Retrieve first looks for a bill of materials at .metadata/com.nvidia.simready.packaging.bom.json and downloads only the files it lists. If the asset has no BOM, Retrieve downloads the whole folder instead. Only a confirmed missing BOM triggers that fallback: a BOM that exists but cannot be read is an error. com.nvidia.simready.packaging.json, when present, names the primary USD.

These two paths are exported as BOM_PATH and PACKAGING_NAME if you need to build or inspect an asset yourself.

Quick start

fetch downloads an asset and returns the local path of its main USD file. It is a coroutine, so await it.

import asyncio
from simready.retrieve import fetch

HF_URL = "hf://my-org/my-repo/crate_01"


async def main():
    # Download only.
    path = await fetch(HF_URL)

    # Download, convert to a profile, and validate the result.
    derived = await fetch(HF_URL, "Target-Profile@1.0.0")

    # Reuse an earlier conversion when the request matches.
    cached = await fetch(
        HF_URL,
        "Target-Profile@1.0.0",
        derive_cache_path="/tmp/simready-derive-cache",
    )
    return path, derived, cached


asyncio.run(main())

Fetch into a workspace

fetch_into_workspace downloads the asset, then adds it to a simready-package workspace and installs it. Use this when you are building a pipeline instead of grabbing a single file. It needs a pinned source: either hf://...@<commit> or a <version>.wkspc URL. A Hugging Face branch name is resolved to its commit for you.

from simready.retrieve import fetch_into_workspace

result = await fetch_into_workspace(HF_URL, "/path/to/workspace")

result.primary_usd      # local path to the main USD file
result.derived_usd      # converted USD, or None if you passed no profile
result.install_path     # where the package was installed
result.package_source   # "workspace" if it was already there, else "network"
result.derive_status    # None, "derived", "cache_hit", or "already_derived"

CLI

simready-retrieve fetch <ASSET_URI>

simready-retrieve -v fetch <ASSET_URI> \
  --profile Target-Profile@1.0.0 \
  --derive-cache-path /tmp/simready-derive-cache

fetch prints the resolved path to stdout and sends everything else to stderr, so you can capture the path on its own.

Flag Purpose
--profile PROFILE@VERSION Convert to an installed profile and validate it
--derive-cache-path DIR Reuse earlier conversions from this directory
--workspace DIR Install into a simready-package workspace
--hf-token TOKEN Hugging Face token; overrides HF_TOKEN and the cached login
--no-browser Print the OmniStorage sign-in URL instead of opening a browser
-v, --verbose Debug logging

Run simready-retrieve auth-clear to delete the cached OmniStorage token.

OpenUSD and Kit

Profiles need OpenUSD (pxr) in the same Python process that calls Retrieve. That is still true when KIT_EXE is set, because Kit runs the conversion but does not give pxr to your process. If nothing else on your system provides OpenUSD, install simready-retrieve[usd]. Do not combine usd-core with USD Exchange.

Conversions run in process through the usd-ingest DirectPipelineBackend. Set KIT_EXE to a kit.sh or kit.exe to run them in Kit instead.

In-process conversions also need the usd-ingest resolver stack: usdex, usd_optimize, and omni_usd_resolver. Install simready-retrieve[deps] to add them. Skip that extra when KIT_EXE is set, because Kit supplies them.

Metadata

Release files for simready-retrieve 2026.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for simready-retrieve 2026.10.0
File Interpreter ABI Platform Actions
simready_retrieve-2026.10.0-py3-none-any.whl Python 3 none any Details for simready_retrieve-2026.10.0-py3-none-any.whl

Release files / simready_retrieve-2026.10.0-py3-none-any.whl

Download URL simready_retrieve-2026.10.0-py3-none-any.whl
Size 117.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cfd33d8cd90a2e968444080022cc6ee251be754d067a2af704666d609520fddc
BLAKE2b-256 checksum
How to use checksums
aa947c113d80808a9eed8f9064e81192987d6f6ef8eeba8179a0968a7f93f107
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Security for simready-retrieve 2026.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2026.10.0 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page