{"record":{"id":"e813002978aefa68","repo":"Lightning-AI/pytorch-lightning","slug":"to-use-the-deepspeedstrategy-you-must-have-deep-e81300","errorCode":null,"errorMessage":"To use the `DeepSpeedStrategy`, you must have DeepSpeed installed. Install it by running `pip install -U deepspeed`.","messagePattern":"To use the `DeepSpeedStrategy`, you must have DeepSpeed installed\\. Install it by running `pip install -U deepspeed`\\.","errorType":"exception","errorClass":"MisconfigurationException","httpStatus":null,"severity":"critical","filePath":"src/lightning/pytorch/strategies/deepspeed.py","lineNumber":262,"sourceCode":"                See `deepspeed tutorial\n                <https://www.deepspeed.ai/tutorials/megatron/#deepspeed-activation-checkpoints-optional>`_.\n\n            cpu_checkpointing: Offloads partitioned activations to CPU if ``partition_activations`` is enabled.\n\n            contiguous_memory_optimization: Copies partitioned activations so that they are contiguous in memory.\n                Not supported by all models.\n\n            synchronize_checkpoint_boundary: Insert :func:`torch.cuda.synchronize` at each checkpoint boundary.\n\n            load_full_weights: True when loading a single checkpoint file containing the model state dict\n                when using ZeRO Stage 3. This differs from the DeepSpeed checkpoint which contains shards\n                per worker.\n\n            exclude_frozen_parameters: Exclude frozen parameters when saving checkpoints.\n\n        \"\"\"\n        if not _DEEPSPEED_AVAILABLE:\n            raise MisconfigurationException(\n                \"To use the `DeepSpeedStrategy`, you must have DeepSpeed installed.\"\n                \" Install it by running `pip install -U deepspeed`.\"\n            )\n\n        if _TORCH_GREATER_EQUAL_2_6 and not _DEEPSPEED_GREATER_EQUAL_0_16:\n            # Starting with PyTorch 2.6, `torch.load` defaults to `weights_only=True` when loading full checkpoints.\n            # DeepSpeed added support for this behavior in version 0.16.0.\n            import deepspeed\n\n            deepspeed_version = deepspeed.__version__\n\n            raise ImportError(\n                f\"PyTorch >= 2.6 requires DeepSpeed >= 0.16.0. \"\n                f\"Detected DeepSpeed version: {deepspeed_version}. \"\n                \"Please upgrade by running `pip install -U 'deepspeed>=0.16.0'`.\"\n            )\n\n        super().__init__(","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/strategies/deepspeed.py#L244-L280","documentation":"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.","triggerScenarios":"Instantiating `DeepSpeedStrategy()` or `Trainer(strategy='deepspeed', ...)` / `Trainer(strategy=DeepSpeedStrategy(), ...)` in an environment where `import deepspeed` fails (module not installed).","commonSituations":"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.","solutions":["Install DeepSpeed in the active environment: `pip install -U deepspeed`","Verify the import works in the same interpreter the Trainer runs under: `python -c \"import deepspeed; print(deepspeed.__version__)\"`","If the import fails due to compiled extensions, ensure a CUDA toolchain is present or install a prebuilt wheel matching your torch/CUDA version"],"exampleFix":"# before\ntrainer = Trainer(strategy=\"deepspeed\", accelerator=\"gpu\")\n\n# after\n# pip install -U deepspeed\ntrainer = Trainer(strategy=\"deepspeed\", accelerator=\"gpu\")","handlingStrategy":"validation","validationCode":"import importlib.util\nif importlib.util.find_spec(\"deepspeed\") is None:\n    raise SystemExit(\"deepspeed not installed: pip install -U deepspeed\")\ntrainer = Trainer(strategy=DeepSpeedStrategy(), accelerator=\"gpu\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Gate DeepSpeed usage behind an import check so CPU-only environments fall back to DDP","Add deepspeed to the project requirements when the Trainer config selects the deepspeed strategy"],"tags":["deepspeed","strategy","dependencies","installation"],"backgroundTag":"missing-optional-dependency","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}