hpcaitech/Open-Sora · error · ImportError

MemEfficientRingAttnProcessor requires xformers, to use it,

Error message

MemEfficientRingAttnProcessor requires xformers, to use it, please install xformers.

What it means

MemEfficientRingAttnProcessor implements memory-efficient ring attention for sequence/context parallelism using the xformers memory-efficient attention kernel. Its __init__ checks the HAS_XFORMERS flag and raises ImportError immediately when xformers is not installed in the environment.

Source

Thrown at opensora/models/hunyuan_vae/distributed.py:275

            Tuple[torch.Tensor, torch.Tensor]: output and log sum exp. Output's shape should be [B, S, N, D]. LSE's shape should be [B, N, S].
        """
        if MemEfficientRingAttention.ATTN_DONE is None:
            MemEfficientRingAttention.ATTN_DONE = torch.cuda.Event()
        if MemEfficientRingAttention.SP_STREAM is None:
            MemEfficientRingAttention.SP_STREAM = torch.cuda.Stream()
        out, softmax_lse = MemEfficientRingAttention.apply(
            q, k, v, sp_group, MemEfficientRingAttention.SP_STREAM, softmax_scale, attn_mask
        )
        if return_softmax:
            return out, softmax_lse
        return out


class MemEfficientRingAttnProcessor:
    def __init__(self, sp_group: dist.ProcessGroup):
        self.sp_group = sp_group
        if not HAS_XFORMERS:
            raise ImportError("MemEfficientRingAttnProcessor requires xformers, to use it, please install xformers.")

    def __call__(
        self,
        attn: Attention,
        hidden_states: torch.Tensor,
        encoder_hidden_states: Optional[torch.Tensor] = None,
        attention_mask: Optional[torch.Tensor] = None,
        temb: Optional[torch.Tensor] = None,
        *args,
        **kwargs,
    ) -> torch.Tensor:
        sp_group = self.sp_group
        assert sp_group is not None, "sp_group must be provided for MemEfficientRingAttnProcessor"

        residual = hidden_states
        if attn.spatial_norm is not None:
            hidden_states = attn.spatial_norm(hidden_states, temb)

View on GitHub (pinned to 7ad6a96a13)

Solutions

1. pip install xformers with a version matched to your torch and CUDA version (see xformers release matrix)
2. If the import fails despite installation, check torch/xformers version compatibility and reinstall the matching pair
3. Fall back to a non-xformers ring attention processor if one is available in distributed.py

Example fix

# before
proc = MemEfficientRingAttnProcessor(sp_group)  # ImportError
# after
# pip install xformers
proc = MemEfficientRingAttnProcessor(sp_group)

try:
    import xformers  # noqa
    HAS_XFORMERS = True
except ImportError:
    HAS_XFORMERS = False
assert HAS_XFORMERS, "install xformers matched to your torch/CUDA before using ring attention"

def has_xformers() -> bool:
    try:
        import xformers  # noqa
        return True
    except ImportError:
        return False

try:
    proc = MemEfficientRingAttnProcessor(sp_group)
except ImportError as e:
    raise RuntimeError("pip install xformers (version matched to torch) to use ring attention") from e

When it happens

Trigger: Constructing MemEfficientRingAttnProcessor(sp_group) — directly or via a context-parallel setup path that builds ring attention processors — in an environment where `import xformers` failed.

Common situations: Running Hunyuan VAE context/sequence parallel inference or training on a box where xformers was never installed, is incompatible with the installed torch/CUDA version, or fails to import due to a broken build.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• ContextParallelAttention should not be initialized directly.

AI-assisted analysis of hpcaitech/Open-Sora@7ad6a96a13 (2026-08-28). Data as JSON: /api/errors/a78b3a1d8ccc14eb. Report an issue: GitHub.