Lightning-AI/pytorch-lightning · error · MisconfigurationException

PyTorch `BasePruningMethod` is currently only supported with

Error message

PyTorch `BasePruningMethod` is currently only supported with `use_global_unstructured=True`.

What it means

If pruning_fn is passed as a custom torch.nn.utils.prune.BasePruningMethod subclass, ModelPruning only supports applying it through the global-unstructured machinery, which requires use_global_unstructured=True (the default). Passing a BasePruningMethod with use_global_unstructured=False raises MisconfigurationException.

Source

Thrown at src/lightning/pytorch/callbacks/pruning.py:202

                    f"The provided `pruning_fn` {pruning_fn} isn't available in PyTorch's"
                    f" built-in functions: {list(_PYTORCH_PRUNING_FUNCTIONS.keys())} "
                )
            if pruning_fn.endswith("_structured"):
                if pruning_dim is None:
                    raise MisconfigurationException(
                        "When requesting `structured` pruning, the `pruning_dim` should be provided."
                    )
                if pruning_fn == "ln_structured":
                    if pruning_norm is None:
                        raise MisconfigurationException(
                            "When requesting `ln_structured` pruning, the `pruning_norm` should be provided."
                        )
                    pruning_kwargs["n"] = pruning_norm
                pruning_kwargs["dim"] = pruning_dim
            pruning_fn = self._create_pruning_fn(pruning_fn, **pruning_kwargs)
        elif self._is_pruning_method(pruning_fn):
            if not use_global_unstructured:
                raise MisconfigurationException(
                    "PyTorch `BasePruningMethod` is currently only supported with `use_global_unstructured=True`."
                )
        else:
            raise MisconfigurationException(
                f"`pruning_fn` is expected to be a str in {list(_PYTORCH_PRUNING_FUNCTIONS.keys())}"
                f" or a PyTorch `BasePruningMethod`. Found: {pruning_fn}."
                " HINT: if passing a `BasePruningMethod`, pass the class, not an instance"
            )

        # need to ignore typing here since pytorch base class does not define the PRUNING_TYPE attribute
        if use_global_unstructured and pruning_fn.PRUNING_TYPE != "unstructured":  # type: ignore
            raise MisconfigurationException(
                'Only the "unstructured" PRUNING_TYPE is supported with `use_global_unstructured=True`.'
                f" Found method {pruning_fn} of type {pruning_fn.PRUNING_TYPE}. "  # type: ignore[union-attr]
            )

        self.pruning_fn = pruning_fn
        self._apply_pruning = apply_pruning

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Remove use_global_unstructured=False (or set it True) when using a BasePruningMethod
2. If you truly need non-global pruning, use a supported built-in string fn (e.g., 'l1_unstructured') with the flag off
3. Consider implementing custom global-unstructured logic by subclassing BasePruningMethod with PRUNING_TYPE='unstructured'

Example fix

# before
ModelPruning(pruning_fn=MyPruningMethod, use_global_unstructured=False)
# after
ModelPruning(pruning_fn=MyPruningMethod, use_global_unstructured=True)

import torch.nn.utils.prune as prune
is_method = isinstance(pruning_fn, type) and issubclass(pruning_fn, prune.BasePruningMethod)
if is_method:
    assert use_global_unstructured is not False

def is_base_pruning_method_cls(fn) -> bool:
    import torch.nn.utils.prune as prune
    return isinstance(fn, type) and issubclass(fn, prune.BasePruningMethod)

When it happens

Trigger: ModelPruning(pruning_fn=MyPruningMethod, use_global_unstructured=False); explicitly disabling global unstructured pruning while still passing a custom method class.

Common situations: Setting use_global_unstructured=False for per-layer/local pruning with a string fn, then later swapping in a custom method without reverting the flag; copying example code that disables the flag.

Related errors

• Only the "unstructured" PRUNING_TYPE is supported with `use_
• Currently only one optimizer is supported with DeepSpeed. Go
• The `PredictionWriterCallback` does not support using `datal
• The provided `parameter_names` name: {name} isn't in {self.P
• The provided `pruning_fn` {pruning_fn} isn't available in Py

AI-assisted analysis of Lightning-AI/pytorch-lightning@9fed5c27d2 (2026-08-28). Data as JSON: /api/errors/f3213a353856e0ad. Report an issue: GitHub.