Fix usd-core 25.8 / usd-exchange ABI conflict by relaxing version pin#5386
Fix usd-core 25.8 / usd-exchange ABI conflict by relaxing version pin#5386fan-ziqi wants to merge 1 commit intoisaac-sim:developfrom
Conversation
Signed-off-by: Ziqi Fan <fanziqi614@gmail.com>
![isaaclab-review-bot[bot]](https://avatars.githubusercontent.com/u/157846462?s=60&v=4){kind=small}
There was a problem hiding this comment.
🤖 Isaac Lab Review Bot
Summary
This PR relaxes the usd-core version pin from ==25.8.0 to >=25.8.0,<26.0.0 to resolve an ABI conflict between usd-core 25.8.0 and usd-exchange 2.2.2, where overlapping pxr/ modules cause RuntimeError at import time. The fix allows pip to resolve to a compatible version (25.11+) that doesn't conflict with usd-exchange.
Architecture Impact
Self-contained. This change affects only the dependency specification in setup.py. The usd-core package provides OpenUSD Python bindings used throughout Isaac Lab's simulation layer (isaaclab.sim, asset loading, USD stage manipulation). The fix enables the packages to coexist without ABI conflicts, but introduces version flexibility that could theoretically bring in untested USD versions. No code changes to Isaac Lab internals.
Implementation Verdict
Minor fixes needed
Test Coverage
No tests are included in this PR. For a dependency version change fixing a runtime crash, adding a CI smoke test that verifies from pxr import Usd succeeds when both usd-core and usd-exchange are installed would be valuable, though the existing CI should implicitly catch regressions if it runs any simulation tests.
CI Status
No CI checks available yet. This is concerning for a dependency change—we need to verify the fix works and doesn't break existing functionality.
Findings
🟡 Warning: source/isaaclab/setup.py:73 — Version range may allow untested USD versions
The range >=25.8.0,<26.0.0 allows any 25.x release (25.8, 25.11, future 25.12, etc.). While the author verified 25.11 works, future 25.x releases are untested. Consider whether >=25.11.0,<26.0.0 would be safer since 25.8.0 is known-broken with usd-exchange:
f"usd-core>=25.11.0,<26.0.0 ; ({SUPPORTED_ARCHS})",This would exclude the broken 25.8.0 entirely rather than hoping pip chooses wisely.
🟡 Warning: source/isaaclab/setup.py:73-74 — Implicit dependency ordering may still cause issues
The fix relies on pip's dependency resolver choosing a compatible usd-core version when usd-exchange is also required. However, pip doesn't guarantee installation order, and the conflict is caused by .so file overwrites during installation. If pip installs usd-core 25.11 after usd-exchange, the ABI mismatch could still occur in reverse. Verify this ordering scenario works in CI.
🔵 Improvement: source/isaaclab/setup.py:71-74 — Add comment explaining the version constraint rationale
Future maintainers will wonder why the version is constrained this way. Add a brief comment:
# Adds OpenUSD dependencies based on architecture for Kit less mode.
# Note: usd-core must be >=25.11 for ABI compatibility with usd-exchange 2.2.x
# (25.8.0 has overlapping pxr/ modules that conflict). Upper bound <26.0.0 for stability.
INSTALL_REQUIRES += [
f"usd-core>=25.8.0,<26.0.0 ; ({SUPPORTED_ARCHS})",🔵 Improvement: PR description truncated — missing constraint explanation
The PR description cuts off mid-sentence at source/isaaclab/setup.py:73: with an incomplete code block. The full context of what the original constraint was and why it was pinned to 25.8.0 specifically would help reviewers understand if there were other reasons for the exact pin (e.g., Isaac Sim 5.1.0 compatibility requirements).
Greptile SummaryThis PR relaxes the Confidence Score: 5/5Safe to merge — the change is a minimal, well-justified dependency relaxation that directly fixes a confirmed ABI conflict. The single-line change is low-risk: it widens a version pin in a controlled way (within the 25.x major family) and the PR description provides concrete verification evidence that 25.11+ resolves the crash. The only remaining finding is a P2 suggestion to add an upper bound on No files require special attention. Important Files Changed
Sequence DiagramsequenceDiagram
participant pip
participant usd_core as usd-core (25.8 → 25.11+)
participant usd_exchange as usd-exchange (2.2.2)
participant pxr as pxr/ modules (on disk)
participant Python
Note over pip: Before fix: ==25.8.0 pinned
pip->>usd_core: install usd-core==25.8.0
usd_core->>pxr: writes pxr/_tf.so (ABI v0_25_8)
pip->>usd_exchange: install usd-exchange>=2.2
usd_exchange->>pxr: overwrites pxr/_tf.so (ABI v0_25_11)
Python->>pxr: from pxr import Usd
pxr-->>Python: RuntimeError (ABI mismatch)
Note over pip: After fix: >=25.8.0,<26.0.0
pip->>usd_core: install usd-core==25.11.x
usd_core->>pxr: writes pxr/_tf.so (ABI v0_25_11)
pip->>usd_exchange: install usd-exchange>=2.2
usd_exchange->>pxr: overwrites pxr/_tf.so (same ABI v0_25_11)
Python->>pxr: from pxr import Usd
pxr-->>Python: OK
Reviews (1): Last reviewed commit: "Update usd-core dependency version range" | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| INSTALL_REQUIRES += [ | ||
| f"usd-core==25.8.0 ; ({SUPPORTED_ARCHS})", | ||
| f"usd-core>=25.8.0,<26.0.0 ; ({SUPPORTED_ARCHS})", | ||
| f"usd-exchange>=2.2 ; ({SUPPORTED_ARCHS_ARM})", |
There was a problem hiding this comment.
usd-exchange
usd-exchange>=2.2 has no upper cap. If a future usd-exchange 2.x release ships pxr/ modules built against a different USD ABI, the same class of conflict can recur. The PR description's own recommendation #2 suggests pinning to known-compatible pairs — adding <2.3 (or whichever version is the next known-good boundary) here would make the constraint self-documenting and guard against silent breakage on the next usd-exchange release.
| f"usd-exchange>=2.2 ; ({SUPPORTED_ARCHS_ARM})", | |
| f"usd-exchange>=2.2,<2.3 ; ({SUPPORTED_ARCHS_ARM})", |
|
Thanks for flagging this @fan-ziqi ! I'm looking into flagging these errors a bit more mechanically. Could you elaborate on why this hapens? What your install setup looks like etc... This way we can test it :) IsaacSim version, which installation etc.. |
2 participants
Description
Bug:
usd-core==25.8.0conflicts withusd-exchangedue to overlappingpxr/modulesEnvironment
developbranch,isaaclab 4.6.12./isaaclab.sh --installProblem
Training scripts fail at startup with:
Import chain:
cartpole_env.py→isaaclab.assets.Articulation→isaaclab.sim.simulation_context→from pxr import Usd→ crashRoot Cause
Both
usd-core25.8.0 andusd-exchange2.2.2 ship identicalpxr/Python modules (.py,.pyc,.sofiles). When installed together viapip install -e, the later-installed packageoverwrites the former's
.sofiles, causing ABI incompatibility.pxr/Tf/_tf.so/opt/USD//builds/omniverse/usd-ci/USD/pxr/Usd/_usd.so/opt/USD//builds/omniverse/usd-ci/USD/pxr/modules)usd-exchange's_tf.sooverwritesusd-core's, butusd-core's monolithiclibusd_ms.sostilllinks against its own ABI. The Boost.Python converter registration fails due to the mismatch.
Verified:
usd-core25.11+ is ABI-compatible withusd-exchange2.2.2. Only 25.8 triggers the conflict.Current Constraints
source/isaaclab/setup.py:73:usd-coreis pinned to exactly 25.8.0, whileusd-exchange>=2.2allows 2.2.2 (which isincompatible with 25.8).
Fix
Relax the version constraint:
Long-term Recommendations
usd-exchangeshould not shippxr/modules — it should depend onusd-coreinstead ofrepackaging the same files. This is a packaging issue on NVIDIA's side.
usd-coreandusd-exchangeshould be constrained toknown-compatible combinations.
from pxr import Usdworks after install.Fixes #5025
Type of change
Checklist
pre-commitchecks with./isaaclab.sh --formatconfig/extension.tomlfileCONTRIBUTORS.mdor my name already exists there