{"record":{"id":"93f50f844ebda487","repo":"Lightning-AI/pytorch-lightning","slug":"launching-multiple-processes-with-the-spawn-star","errorCode":null,"errorMessage":"Launching multiple processes with the 'spawn' start method requires that your script guards the main function with an `if __name__ == \"__main__\"` clause. For example:\n\ndef main():\n    # Put your code here\n    ...\n\nif __name__ == \"__main__\":\n    main()\n\nAlternatively, you can run with `strategy=\"ddp\"` to avoid this error.","messagePattern":"Launching multiple processes with the 'spawn' start method requires that your script guards the main function with an `if __name__ == \"__main__\"` clause\\. For example:\n\ndef main\\(\\):\n    # Put your code here\n    \\.\\.\\.\n\nif __name__ == \"__main__\":\n    main\\(\\)\n\nAlternatively, you can run with `strategy=\"ddp\"` to avoid this error\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/strategies/launchers/multiprocessing.py","lineNumber":261,"sourceCode":"    \"\"\"Raises an exception if the ``__name__ == \"__main__\"`` guard is missing.\"\"\"\n    if not getattr(mp.current_process(), \"_inheriting\", False):\n        return\n    message = dedent(\n        \"\"\"\n        Launching multiple processes with the 'spawn' start method requires that your script guards the main\n        function with an `if __name__ == \\\"__main__\\\"` clause. For example:\n\n        def main():\n            # Put your code here\n            ...\n\n        if __name__ == \"__main__\":\n            main()\n\n        Alternatively, you can run with `strategy=\"ddp\"` to avoid this error.\n        \"\"\"\n    )\n    raise RuntimeError(message)\n","sourceCodeStart":243,"sourceCodeEnd":262,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/strategies/launchers/multiprocessing.py#L243-L262","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Wrap all launch code in a main() function and call it under if __name__ == '__main__':","Alternatively use strategy='ddp', which launches via subprocess scripts and doesn't need the guard","Ensure anything importable (model definitions, helpers) is defined at module level so children can import it, but keep execution guarded"],"exampleFix":"# before\nfabric = Fabric(strategy=\"ddp_spawn\", devices=2)\nfabric.run(main)  # runs at import time in every child\n\n# after\ndef main():\n    fabric = Fabric(strategy=\"ddp_spawn\", devices=2)\n    fabric.run(train)\n\nif __name__ == \"__main__\":\n    main()","handlingStrategy":"validation","validationCode":"import __main__ as m\nif getattr(m, \"__spec__\", None) is None and __name__ != \"__main__\":\n    raise RuntimeError(\"script lacks if __name__ == '__main__' guard; required for spawn\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always template multi-process scripts with a main() + __main__ guard","Use strategy='ddp' (subprocess launcher) for scripts you can't modify"],"tags":["pytorch-lightning","multiprocessing","spawn","entry-point","guard"],"backgroundTag":"missing-main-guard-spawn","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}