Lightning-AI/pytorch-lightning · critical · MisconfigurationException

To use the `DeepSpeedStrategy`, you must have DeepSpeed inst

Error message

To use the `DeepSpeedStrategy`, you must have DeepSpeed installed. Install it by running `pip install -U deepspeed`.

What it means

DeepSpeedStrategy's __init__ checks whether the `deepspeed` package is importable and refuses to construct the strategy without it. Lightning does not bundle DeepSpeed; it is an optional heavy dependency that must be installed separately. The error is raised eagerly so the user fails fast before training starts.

Source

Thrown at src/lightning/pytorch/strategies/deepspeed.py:262

                See `deepspeed tutorial
                <https://www.deepspeed.ai/tutorials/megatron/#deepspeed-activation-checkpoints-optional>`_.

            cpu_checkpointing: Offloads partitioned activations to CPU if ``partition_activations`` is enabled.

            contiguous_memory_optimization: Copies partitioned activations so that they are contiguous in memory.
                Not supported by all models.

            synchronize_checkpoint_boundary: Insert :func:`torch.cuda.synchronize` at each checkpoint boundary.

            load_full_weights: True when loading a single checkpoint file containing the model state dict
                when using ZeRO Stage 3. This differs from the DeepSpeed checkpoint which contains shards
                per worker.

            exclude_frozen_parameters: Exclude frozen parameters when saving checkpoints.

        """
        if not _DEEPSPEED_AVAILABLE:
            raise MisconfigurationException(
                "To use the `DeepSpeedStrategy`, you must have DeepSpeed installed."
                " Install it by running `pip install -U deepspeed`."
            )

        if _TORCH_GREATER_EQUAL_2_6 and not _DEEPSPEED_GREATER_EQUAL_0_16:
            # Starting with PyTorch 2.6, `torch.load` defaults to `weights_only=True` when loading full checkpoints.
            # DeepSpeed added support for this behavior in version 0.16.0.
            import deepspeed

            deepspeed_version = deepspeed.__version__

            raise ImportError(
                f"PyTorch >= 2.6 requires DeepSpeed >= 0.16.0. "
                f"Detected DeepSpeed version: {deepspeed_version}. "
                "Please upgrade by running `pip install -U 'deepspeed>=0.16.0'`."
            )

        super().__init__(

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Install DeepSpeed in the active environment: `pip install -U deepspeed`
2. Verify the import works in the same interpreter the Trainer runs under: `python -c "import deepspeed; print(deepspeed.__version__)"`
3. If the import fails due to compiled extensions, ensure a CUDA toolchain is present or install a prebuilt wheel matching your torch/CUDA version

Example fix

# before
trainer = Trainer(strategy="deepspeed", accelerator="gpu")

# after
# pip install -U deepspeed
trainer = Trainer(strategy="deepspeed", accelerator="gpu")

import importlib.util
if importlib.util.find_spec("deepspeed") is None:
    raise SystemExit("deepspeed not installed: pip install -U deepspeed")
trainer = Trainer(strategy=DeepSpeedStrategy(), accelerator="gpu")

When it happens

Trigger: Instantiating `DeepSpeedStrategy()` or `Trainer(strategy='deepspeed', ...)` / `Trainer(strategy=DeepSpeedStrategy(), ...)` in an environment where `import deepspeed` fails (module not installed).

Common situations: Fresh environment where only `lightning` / `pytorch-lightning` was installed; installing Lightning with `[extra]` bundles that omit deepspeed; a broken deepspeed install (failed CUDA extension build) that makes the import fail; wrong conda env/interpreter.

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

• accelerator set through both strategy class and accelerator
• precision set through both strategy class and plugins, choos
• checkpoint_io set through both strategy class and plugins, c
• cluster_environment set through both strategy class and plug
• CPU parallel_devices set through {self._strategy_flag.__clas

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