Lightning-AI/pytorch-lightning · error · MisconfigurationException

`Trainer(strategy={self._strategy_flag!r})` is not compatibl

Error message

`Trainer(strategy={self._strategy_flag!r})` is not compatible with an interactive environment. Run your code as a script, or choose a notebook-compatible strategy: `Trainer(strategy='ddp_notebook')`. In case you are spawning processes yourself, make sure to include the Trainer creation inside the worker function.

What it means

Certain strategies spawn subprocesses via a launcher that is not compatible with interactive environments (Jupyter/IPython). If Lightning detects an interactive session (sys.modules/psutil heuristics) and the configured launcher lacks is_interactive_compatible, it raises MisconfigurationException during strategy init.

Source

Thrown at src/lightning/pytorch/trainer/connectors/accelerator_connector.py:535

        if hasattr(self.strategy, "cluster_environment"):
            if self.strategy.cluster_environment is None:
                self.strategy.cluster_environment = self.cluster_environment
            self.cluster_environment = self.strategy.cluster_environment
        if hasattr(self.strategy, "parallel_devices"):
            if self.strategy.parallel_devices:
                self._parallel_devices = self.strategy.parallel_devices
            else:
                self.strategy.parallel_devices = self._parallel_devices
        if hasattr(self.strategy, "num_nodes"):
            self.strategy.num_nodes = self._num_nodes_flag
        if hasattr(self.strategy, "_layer_sync"):
            self.strategy._layer_sync = self._layer_sync
        if hasattr(self.strategy, "set_world_ranks"):
            self.strategy.set_world_ranks()
        self.strategy._configure_launcher()

        if _IS_INTERACTIVE and self.strategy.launcher and not self.strategy.launcher.is_interactive_compatible:
            raise MisconfigurationException(
                f"`Trainer(strategy={self._strategy_flag!r})` is not compatible with an interactive"
                " environment. Run your code as a script, or choose a notebook-compatible strategy:"
                f" `Trainer(strategy='ddp_notebook')`."
                " In case you are spawning processes yourself, make sure to include the Trainer"
                " creation inside the worker function."
            )

        # TODO: should be moved to _check_strategy_and_fallback().
        # Current test check precision first, so keep this check here to meet error order
        if isinstance(self.accelerator, XLAAccelerator) and not isinstance(
            self.strategy, (SingleDeviceXLAStrategy, XLAStrategy)
        ):
            raise ValueError(
                "The `XLAAccelerator` can only be used with a `SingleDeviceXLAStrategy` or `XLAStrategy`,"
                f" found {self.strategy.__class__.__name__}."
            )

    @property

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Use Trainer(strategy='ddp_notebook') (or 'ddp_fork' style interactive-compatible strategy) inside notebooks
2. Move Trainer creation and training into a .py script and run it with python/launcher outside the interactive session
3. If spawning processes yourself, create the Trainer inside the worker function as the message advises

Example fix

# before
# in Jupyter
trainer = Trainer(strategy="ddp", accelerator="gpu", devices=2)
# after
# in Jupyter
trainer = Trainer(strategy="ddp_notebook", accelerator="gpu", devices=2)

import sys
INTERACTIVE = "ipykernel" in sys.modules or "IPython" in sys.modules
if INTERACTIVE and strategy in ("ddp", "ddp_spawn", "deepspeed"):
    strategy = "ddp_notebook"
trainer = Trainer(strategy=strategy)

def is_interactive() -> bool:
    import sys
    return "ipykernel" in sys.modules or "IPython" in sys.modules

from lightning.pytorch.utilities.exceptions import MisconfigurationException
try:
    trainer = Trainer(strategy="ddp")
except MisconfigurationException as e:
    if "interactive" in str(e):
        trainer = Trainer(strategy="ddp_notebook")
    else:
        raise

When it happens

Trigger: Trainer(strategy='ddp') (or ddp_spawn/deepspeed etc. with non-interactive launchers) inside Jupyter/IPython/VS Code interactive windows.

Common situations: Prototyping distributed training in notebooks; tutorials using ddp in Colab; running ddp scripts line-by-line in IDE consoles.

Related errors

• Blocking backward sync is only possible if the module passed
• The launcher can only create subprocesses once.
• Trying to inject a modified sampler into the batch sampler;
• Lightning can't inject a (distributed) sampler into your ba
• You are calling the method `{type(self._original_module).__n

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