{"record":{"id":"205b8e4f81bdd1f8","repo":"Lightning-AI/pytorch-lightning","slug":"to-use-the-deepspeedstrategy-you-must-have-deep","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":"ImportError","httpStatus":null,"severity":"critical","filePath":"src/lightning/fabric/strategies/deepspeed.py","lineNumber":241,"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 ImportError(\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":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/strategies/deepspeed.py#L223-L259","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["pip install -U deepspeed","Verify 'python -c \"import deepspeed\"' succeeds in the exact env/interpreter used","If deepspeed is optional in your project, catch ImportError and fall back to DDPStrategy"],"exampleFix":"# before\nstrategy = DeepSpeedStrategy(stage=3)\n# after (shell)\npip install -U deepspeed\n# or code fallback\ntry:\n    strategy = DeepSpeedStrategy(stage=3)\nexcept ImportError:\n    strategy = DDPStrategy()","handlingStrategy":"try-catch","validationCode":"import importlib.util\nif importlib.util.find_spec(\"deepspeed\") is None:\n    raise RuntimeError(\"deepspeed missing; cannot use DeepSpeedStrategy\")","typeGuard":"import importlib.util\n\ndef deepspeed_available() -> bool:\n    return importlib.util.find_spec(\"deepspeed\") is not None","tryCatchPattern":"try:\n    strategy = DeepSpeedStrategy(stage=3)\nexcept ImportError:\n    strategy = DDPStrategy()  # documented fallback","preventionTips":["Add deepspeed to your training environment spec/lockfile","Smoke-test 'import deepspeed' in CI for deepspeed jobs"],"tags":["deepspeed","missing-dependency","import-error","pytorch-lightning"],"backgroundTag":"missing-optional-dependency","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}