{"record":{"id":"eeb85a1841cc7adf","repo":"open-mmlab/mmdetection","slug":"if-you-want-to-reduce-gpu-memory-usage","errorCode":null,"errorMessage":"If you want to reduce GPU memory usage,                     please install fairscale by executing the                     following command: pip install fairscale.","messagePattern":"If you want to reduce GPU memory usage,                     please install fairscale by executing the                     following command: pip install fairscale\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"mmdet/models/layers/transformer/deformable_detr_layers.py","lineNumber":33,"sourceCode":"try:\n    from fairscale.nn.checkpoint import checkpoint_wrapper\nexcept Exception:\n    checkpoint_wrapper = None\n\n\nclass DeformableDetrTransformerEncoder(DetrTransformerEncoder):\n    \"\"\"Transformer encoder of Deformable DETR.\"\"\"\n\n    def _init_layers(self) -> None:\n        \"\"\"Initialize encoder layers.\"\"\"\n        self.layers = ModuleList([\n            DeformableDetrTransformerEncoderLayer(**self.layer_cfg)\n            for _ in range(self.num_layers)\n        ])\n\n        if self.num_cp > 0:\n            if checkpoint_wrapper is None:\n                raise NotImplementedError(\n                    'If you want to reduce GPU memory usage, \\\n                    please install fairscale by executing the \\\n                    following command: pip install fairscale.')\n            for i in range(self.num_cp):\n                self.layers[i] = checkpoint_wrapper(self.layers[i])\n\n        self.embed_dims = self.layers[0].embed_dims\n\n    def forward(self, query: Tensor, query_pos: Tensor,\n                key_padding_mask: Tensor, spatial_shapes: Tensor,\n                level_start_index: Tensor, valid_ratios: Tensor,\n                **kwargs) -> Tensor:\n        \"\"\"Forward function of Transformer encoder.\n\n        Args:\n            query (Tensor): The input query, has shape (bs, num_queries, dim).\n            query_pos (Tensor): The positional encoding for query, has shape\n                (bs, num_queries, dim).","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/open-mmlab/mmdetection/blob/cfd5d3a985b0249de009b67d04f37263e11cdf3d/mmdet/models/layers/transformer/deformable_detr_layers.py#L15-L51","documentation":"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.","triggerScenarios":"Config with num_cp>0 in the deformable DETR transformer encoder while `import fairscale.nn.utils.checkpoint_wrapper` failed (fairscale not installed).","commonSituations":"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.","solutions":["pip install fairscale","Or set num_cp=0 in the transformer config to disable layer checkpointing"],"exampleFix":"# before\npip install mmdet  # num_cp=2 in config\n# after\npip install fairscale\n# or set num_cp=0 in the deformable transformer encoder cfg","handlingStrategy":"validation","validationCode":"from mmdet.registry import MODELS\nif num_cp > 0:\n    try:\n        from fairscale.nn.utils import checkpoint_wrapper\n    except ImportError:\n        raise SystemExit('pip install fairscale or set num_cp=0')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install fairscale when using num_cp>0 configs","Record dependencies in environment.yml/dockerfile"],"tags":["mmdet","deformable-detr","fairscale","dependency","gpu-memory"],"backgroundTag":"missing-dependency","analyzedSha":"cfd5d3a985b0249de009b67d04f37263e11cdf3d","analyzedAt":"2026-08-27T20:54:20.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}