Lightning-AI/pytorch-lightning · critical · ImportError

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 requires the deepspeed package. Its module-level availability check failed, and the constructor raises this ImportError with install instructions, so you cannot construct the strategy at all without the dependency.

Source

Thrown at src/lightning/fabric/strategies/deepspeed.py:241

                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 ImportError(
                "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. pip install -U deepspeed
2. Verify 'python -c "import deepspeed"' succeeds in the exact env/interpreter used
3. If deepspeed is optional in your project, catch ImportError and fall back to DDPStrategy

Example fix

# before
strategy = DeepSpeedStrategy(stage=3)
# after (shell)
pip install -U deepspeed
# or code fallback
try:
    strategy = DeepSpeedStrategy(stage=3)
except ImportError:
    strategy = DDPStrategy()

import importlib.util
if importlib.util.find_spec("deepspeed") is None:
    raise RuntimeError("deepspeed missing; cannot use DeepSpeedStrategy")

import importlib.util

def deepspeed_available() -> bool:
    return importlib.util.find_spec("deepspeed") is not None

try:
    strategy = DeepSpeedStrategy(stage=3)
except ImportError:
    strategy = DDPStrategy()  # documented fallback

When it happens

Trigger: DeepSpeedStrategy(...) (or Fabric(strategy='deepspeed')) in an environment where 'import deepspeed' fails — package not installed, or installed but failing to import due to a missing compiler/CUDA runtime.

Common situations: Running a deepspeed-configured training script in a fresh env/CI container; deepspeed imported on a machine without a working C++ build toolchain so the JIT import fails.

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

• Neither `tensorboard` nor `tensorboardX` is available. Try `
• `precision={precision!r})` is not supported in DeepSpeed. `p
• str(_TRANSFORMER_ENGINE_AVAILABLE)
• str(_XLA_AVAILABLE)
• PyTorch >= 2.6 requires DeepSpeed >= 0.16.0. Detected DeepSp

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