Lightning-AI/pytorch-lightning · error · RuntimeError

Launching multiple processes with the 'spawn' start method r

Error message

Launching multiple processes with the 'spawn' start method requires that your script guards the main function with an `if __name__ == "__main__"` clause. For example:

def main():
    # Put your code here
    ...

if __name__ == "__main__":
    main()

Alternatively, you can run with `strategy="ddp"` to avoid this error.

What it means

When the 'spawn' start method is used, Python re-imports the main module in each child process; without an if __name__ == "__main__" guard this causes infinite process spawning. Lightning therefore requires the entry script to guard its main function before launching spawned workers, and suggests the subprocess-based 'ddp' strategy as an alternative.

Source

Thrown at src/lightning/fabric/strategies/launchers/multiprocessing.py:261

    """Raises an exception if the ``__name__ == "__main__"`` guard is missing."""
    if not getattr(mp.current_process(), "_inheriting", False):
        return
    message = dedent(
        """
        Launching multiple processes with the 'spawn' start method requires that your script guards the main
        function with an `if __name__ == \"__main__\"` clause. For example:

        def main():
            # Put your code here
            ...

        if __name__ == "__main__":
            main()

        Alternatively, you can run with `strategy="ddp"` to avoid this error.
        """
    )
    raise RuntimeError(message)

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Wrap all launch code in a main() function and call it under if __name__ == '__main__':
2. Alternatively use strategy='ddp', which launches via subprocess scripts and doesn't need the guard
3. Ensure anything importable (model definitions, helpers) is defined at module level so children can import it, but keep execution guarded

Example fix

# before
fabric = Fabric(strategy="ddp_spawn", devices=2)
fabric.run(main)  # runs at import time in every child

# after
def main():
    fabric = Fabric(strategy="ddp_spawn", devices=2)
    fabric.run(train)

if __name__ == "__main__":
    main()

import __main__ as m
if getattr(m, "__spec__", None) is None and __name__ != "__main__":
    raise RuntimeError("script lacks if __name__ == '__main__' guard; required for spawn")

When it happens

Trigger: Running a script that executes Fabric(...).run(...) / launcher.launch(...) at module top level with strategy='ddp_spawn' (or any spawn-based launcher) and no if __name__ == '__main__' guard; also common in converted single-process scripts.

Common situations: Quick experiments converted to multi-process DDP; tutorials run as 'python script.py' where code sits at module scope; Jupyter users switching to a .py file but omitting the guard.

Related errors

• Cannot re-initialize CUDA in forked subprocess. To use CUDA
• The start method '{self._start_method}' is not available on
• Lightning can't create new processes if CUDA is already init
• The start method '{self._start_method}' is not available on
• Calling `trainer.fit()` twice on the same Trainer instance u

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