Genesis-Embodied-AI/genesis-world · error · ImportError

Python module 'uipc' is required by IPCCoupler but is not in

Error message

Python module 'uipc' is required by IPCCoupler but is not installed. Please install it via `pip install pyuipc`.

What it means

IPCCoupler (the IPC-based rigid-deformable coupler) delegates core geometry and collision computations to the external `uipc` Python package. At init it checks the UIPC_AVAILABLE flag set by a module-level import probe; if pyuipc is absent it refuses to construct. The simulator core works without it, only this coupler requires it.

Source

Thrown at genesis/engine/couplers/ipc_coupler/coupler.py:113

    This coupler manages the communication between Genesis solvers and the IPC system,
    including rigid bodies (as ABD objects) and FEM bodies in a unified contact framework.
    """

    def __init__(self, simulator: "Simulator", options: IPCCouplerOptions) -> None:
        """
        Initialize IPC Coupler.

        Parameters
        ----------
        simulator : Simulator
            The simulator containing all solvers
        options : IPCCouplerOptions
            IPC configuration options
        """
        # Check if uipc is available
        if not UIPC_AVAILABLE:
            raise ImportError(
                "Python module 'uipc' is required by IPCCoupler but is not installed. Please install it via "
                "`pip install pyuipc`."
            )

        self.sim = simulator
        self.options = options

        # Define some proxies for convenience
        self.rigid_solver: "RigidSolver" = self.sim.rigid_solver
        self.fem_solver: "FEMSolver" = self.sim.fem_solver

        # ==== IPC System Infrastructure ====
        # The soft-constraint strengths coupling a rigid body to its Genesis pose, 'constraint_strength_translation'
        # and 'constraint_strength_rotation', are scaled by the inverse square of the substep interval to reach the
        # units the IPC world expects. That interval is only known once every solver has derived its substeps, so the
        # initialization of both of them, and of the IPC scene, is postponed to build time.
        self._constraint_strength_translation_scaled: float | None = None
        self._constraint_strength_rotation_scaled: float | None = None

View on GitHub (pinned to 56e4aa5d82)

Solutions

  1. `pip install pyuipc` in the active environment.
  2. If you do not need IPC coupling, remove the IPCCoupler / switch the hybrid material to not use IPC (`use_default_coupling=False` with your own association functions, or a different coupler).
  3. Verify with `python -c "import uipc"` that the install landed in the same interpreter Genesis runs under.

Example fix

# before
coupler = gs.couplers.IPCCoupler(sim)  # ImportError

# after
pip install pyuipc
coupler = gs.couplers.IPCCoupler(sim)
Defensive patterns

Strategy: validation

Validate before calling

from genesis.utils import misc  # or check importability directly
import importlib.util
if importlib.util.find_spec("uipc") is None:
    raise SystemExit("IPCCoupler requires pyuipc: pip install pyuipc")

Try / catch

try:
    coupler = gs.couplers.IPCCoupler(sim)
except ImportError as e:
    if "pyuipc" in str(e):
        subprocess.check_call([sys.executable, "-m", "pip", "install", "pyuipc"])
    raise

Prevention

When it happens

Trigger: Constructing `gs.couplers.IPCCoupler(sim, options)` (or letting a scene build a hybrid entity with default IPC coupling) in an environment where `pip install pyuipc` was never executed.

Common situations: Running hybrid rigid-soft examples (e.g. examples coupling a rigid robot with deformables) on a machine that only installed the base genesis requirements; CI images trimmed to core deps; a fresh venv after cloning.

Related errors

AI-assisted analysis of Genesis-Embodied-AI/genesis-world@56e4aa5d82 (2026-08-28). Data as JSON: /api/errors/d4525b22ae42bf4d. Report an issue: GitHub.