open-mmlab/mmdetection · error · NotImplementedError

If you want to reduce GPU memory usage,

Error message

If you want to reduce GPU memory usage,                     please install fairscale by executing the                     following command: pip install fairscale.

What it means

Raised when DeformableDetrTransformerEncoder is configured with num_cp > 0 (activation checkpointing layers) but the optional fairscale package is not installed, since mmdet uses fairscale's checkpoint_wrapper to wrap encoder layers.

Source

Thrown at mmdet/models/layers/transformer/deformable_detr_layers.py:33

try:
    from fairscale.nn.checkpoint import checkpoint_wrapper
except Exception:
    checkpoint_wrapper = None


class DeformableDetrTransformerEncoder(DetrTransformerEncoder):
    """Transformer encoder of Deformable DETR."""

    def _init_layers(self) -> None:
        """Initialize encoder layers."""
        self.layers = ModuleList([
            DeformableDetrTransformerEncoderLayer(**self.layer_cfg)
            for _ in range(self.num_layers)
        ])

        if self.num_cp > 0:
            if checkpoint_wrapper is None:
                raise NotImplementedError(
                    'If you want to reduce GPU memory usage, \
                    please install fairscale by executing the \
                    following command: pip install fairscale.')
            for i in range(self.num_cp):
                self.layers[i] = checkpoint_wrapper(self.layers[i])

        self.embed_dims = self.layers[0].embed_dims

    def forward(self, query: Tensor, query_pos: Tensor,
                key_padding_mask: Tensor, spatial_shapes: Tensor,
                level_start_index: Tensor, valid_ratios: Tensor,
                **kwargs) -> Tensor:
        """Forward function of Transformer encoder.

        Args:
            query (Tensor): The input query, has shape (bs, num_queries, dim).
            query_pos (Tensor): The positional encoding for query, has shape
                (bs, num_queries, dim).

View on GitHub (pinned to cfd5d3a985)

Solutions

1. pip install fairscale
2. Or set num_cp=0 in the transformer config to disable layer checkpointing

Example fix

# before
pip install mmdet  # num_cp=2 in config
# after
pip install fairscale
# or set num_cp=0 in the deformable transformer encoder cfg

from mmdet.registry import MODELS
if num_cp > 0:
    try:
        from fairscale.nn.utils import checkpoint_wrapper
    except ImportError:
        raise SystemExit('pip install fairscale or set num_cp=0')

When it happens

Trigger: Config with num_cp>0 in the deformable DETR transformer encoder while `import fairscale.nn.utils.checkpoint_wrapper` failed (fairscale not installed).

Common situations: Copying memory-efficient configs that assume fairscale; fresh environments where only mmcv/mmdet were installed; GPU OOM workarounds that enable num_cp without installing the dependency.

Related errors

• If you want to reduce GPU memory usage,
• If you want to reduce GPU memory usage,
• imagecorruptions is not installed
• albumentations is not installed
• There is not post_norm in {name}

AI-assisted analysis of open-mmlab/mmdetection@cfd5d3a985 (2026-08-27). Data as JSON: /api/errors/eeb85a1841cc7adf. Report an issue: GitHub.