Add raise_exceptions parameter to multiprocessing.set_forkserver_preload

Add a keyword-only `raise_exceptions` parameter (default False) to
`multiprocessing.set_forkserver_preload()`. When True, ImportError
exceptions during module preloading cause the forkserver to exit,
breaking all use of the forkserver multiprocessing context. This
allows developers to catch import errors during development rather
than having them silently ignored.

Implementation adds the parameter to both the ForkServer class method
and the BaseContext wrapper, passing it through to the forkserver
main() function which conditionally raises ImportError instead of
ignoring it.

Tests are in new test_multiprocessing_forkserver/test_preload.py with
proper resource cleanup using try/finally.

Documentation describes the behavior, consequences (forkserver exit,
EOFError/ConnectionError on subsequent use), and recommends use during
development.

Based on original work by Nick Neumann in GH-99515.
Contributed by Nick Neumann.

Co-authored-by: Gregory P. Smith <greg@krypto.org>

Author: gpshead

Doc/library/multiprocessing.rst

@@ -1211,22 +1211,31 @@ Miscellaneous
    .. versionchanged:: 3.11
       Accepts a :term:`path-like object`.
 
-.. function:: set_forkserver_preload(module_names)
+.. function:: set_forkserver_preload(module_names, *, raise_exceptions=False)
 
    Set a list of module names for the forkserver main process to attempt to
    import so that their already imported state is inherited by forked
-   processes. Any :exc:`ImportError` when doing so is silently ignored.
-   This can be used as a performance enhancement to avoid repeated work
-   in every process.
+   processes. This can be used as a performance enhancement to avoid repeated
+   work in every process.
 
    For this to work, it must be called before the forkserver process has been
    launched (before creating a :class:`Pool` or starting a :class:`Process`).
 
+   By default, any :exc:`ImportError` when importing modules is silently
+   ignored. If *raise_exceptions* is ``True``, :exc:`ImportError` exceptions
+   will be raised in the forkserver subprocess, causing it to exit. The
+   exception traceback will appear on stderr, and subsequent attempts to
+   create processes will fail with :exc:`EOFError` or :exc:`ConnectionError`.
+   Use *raise_exceptions* during development to catch import problems early.
+
    Only meaningful when using the ``'forkserver'`` start method.
    See :ref:`multiprocessing-start-methods`.
 
    .. versionadded:: 3.4
 
+   .. versionchanged:: next
+      Added the *raise_exceptions* parameter.
+
 .. function:: set_start_method(method, force=False)
 
    Set the method which should be used to start child processes.

Lib/multiprocessing/context.py

@@ -177,12 +177,15 @@ def set_executable(self, executable):
         from .spawn import set_executable
         set_executable(executable)
 
-    def set_forkserver_preload(self, module_names):
+    def set_forkserver_preload(self, module_names, *, raise_exceptions=False):
         '''Set list of module names to try to load in forkserver process.
-        This is really just a hint.
+
+        If raise_exceptions is True, ImportError exceptions during preload
+        will be raised instead of being silently ignored. Such errors will
+        break all use of the forkserver multiprocessing context.
         '''
         from .forkserver import set_forkserver_preload
-        set_forkserver_preload(module_names)
+        set_forkserver_preload(module_names, raise_exceptions=raise_exceptions)
 
     def get_context(self, method=None):
         if method is None:

Lib/multiprocessing/forkserver.py

@@ -42,6 +42,7 @@ def __init__(self):
         self._inherited_fds = None
         self._lock = threading.Lock()
         self._preload_modules = ['__main__']
+        self._raise_exceptions = False
 
     def _stop(self):
         # Method used by unit tests to stop the server
@@ -64,11 +65,17 @@ def _stop_unlocked(self):
         self._forkserver_address = None
         self._forkserver_authkey = None
 
-    def set_forkserver_preload(self, modules_names):
-        '''Set list of module names to try to load in forkserver process.'''
+    def set_forkserver_preload(self, modules_names, *, raise_exceptions=False):
+        '''Set list of module names to try to load in forkserver process.
+
+        If raise_exceptions is True, ImportError exceptions during preload
+        will be raised instead of being silently ignored. Such errors will
+        break all use of the forkserver multiprocessing context.
+        '''
         if not all(type(mod) is str for mod in modules_names):
             raise TypeError('module_names must be a list of strings')
         self._preload_modules = modules_names
+        self._raise_exceptions = raise_exceptions
 
     def get_inherited_fds(self):
         '''Return list of fds inherited from parent process.
@@ -152,6 +159,8 @@ def ensure_running(self):
                     main_kws['sys_path'] = data['sys_path']
                 if 'init_main_from_path' in data:
                     main_kws['main_path'] = data['init_main_from_path']
+                if self._raise_exceptions:
+                    main_kws['raise_exceptions'] = True
 
             with socket.socket(socket.AF_UNIX) as listener:
                 address = connection.arbitrary_address('AF_UNIX')
@@ -197,7 +206,7 @@ def ensure_running(self):
 #
 
 def main(listener_fd, alive_r, preload, main_path=None, sys_path=None,
-         *, authkey_r=None):
+         *, authkey_r=None, raise_exceptions=False):
     """Run forkserver."""
     if authkey_r is not None:
         try:
@@ -221,6 +230,8 @@ def main(listener_fd, alive_r, preload, main_path=None, sys_path=None,
             try:
                 __import__(modname)
             except ImportError:
+                if raise_exceptions:
+                    raise
                 pass
 
         # gh-135335: flush stdout/stderr in case any of the preloaded modules

Lib/test/test_multiprocessing_forkserver/test_preload.py

@@ -0,0 +1,96 @@
+"""Tests for forkserver preload functionality."""
+
+import multiprocessing
+import multiprocessing.forkserver
+import sys
+import unittest
+
+
+@unittest.skipIf(sys.platform == "win32", "forkserver not available on Windows")
+class TestForkserverPreload(unittest.TestCase):
+    """Tests for forkserver preload functionality."""
+
+    def setUp(self):
+        self.ctx = multiprocessing.get_context('forkserver')
+        # Ensure clean state for each test
+        multiprocessing.forkserver._forkserver._stop()
+
+    def tearDown(self):
+        # Clean up after tests
+        multiprocessing.forkserver._forkserver._stop()
+        self.ctx.set_forkserver_preload([])
+
+    @staticmethod
+    def _send_value(conn, value):
+        """Helper to send a value through a connection."""
+        conn.send(value)
+
+    def test_preload_raise_exceptions_false_default(self):
+        """Test that invalid modules are silently ignored by default."""
+        # With raise_exceptions=False (default), invalid module is ignored
+        self.ctx.set_forkserver_preload(['nonexistent_module_xyz'])
+
+        # Should be able to start a process without errors
+        r, w = self.ctx.Pipe(duplex=False)
+        p = self.ctx.Process(target=self._send_value, args=(w, 42))
+        p.start()
+        w.close()
+        result = r.recv()
+        r.close()
+        p.join()
+
+        self.assertEqual(result, 42)
+        self.assertEqual(p.exitcode, 0)
+
+    def test_preload_raise_exceptions_false_explicit(self):
+        """Test that invalid modules are silently ignored with raise_exceptions=False."""
+        self.ctx.set_forkserver_preload(['nonexistent_module_xyz'], raise_exceptions=False)
+
+        # Should be able to start a process without errors
+        r, w = self.ctx.Pipe(duplex=False)
+        p = self.ctx.Process(target=self._send_value, args=(w, 99))
+        p.start()
+        w.close()
+        result = r.recv()
+        r.close()
+        p.join()
+
+        self.assertEqual(result, 99)
+        self.assertEqual(p.exitcode, 0)
+
+    def test_preload_raise_exceptions_true_breaks_context(self):
+        """Test that invalid modules with raise_exceptions=True breaks the forkserver."""
+        self.ctx.set_forkserver_preload(['nonexistent_module_xyz'], raise_exceptions=True)
+
+        # The forkserver should fail to start when it tries to import
+        # The exception is raised during p.start() when trying to communicate
+        # with the failed forkserver process
+        r, w = self.ctx.Pipe(duplex=False)
+        try:
+            p = self.ctx.Process(target=self._send_value, args=(w, 42))
+            with self.assertRaises((EOFError, ConnectionError, BrokenPipeError)):
+                p.start()  # Exception raised here
+        finally:
+            # Ensure pipes are closed even if exception is raised
+            w.close()
+            r.close()
+
+    def test_preload_valid_modules_with_raise_exceptions(self):
+        """Test that valid modules work fine with raise_exceptions=True."""
+        # Valid modules should work even with raise_exceptions=True
+        self.ctx.set_forkserver_preload(['os', 'sys'], raise_exceptions=True)
+
+        r, w = self.ctx.Pipe(duplex=False)
+        p = self.ctx.Process(target=self._send_value, args=(w, 'success'))
+        p.start()
+        w.close()
+        result = r.recv()
+        r.close()
+        p.join()
+
+        self.assertEqual(result, 'success')
+        self.assertEqual(p.exitcode, 0)
+
+
+if __name__ == '__main__':
+    unittest.main()

Misc/ACKS

@@ -1337,6 +1337,7 @@ Trent Nelson
 Andrew Nester
 Osvaldo Santana Neto
 Chad Netzer
+Nick Neumann
 Max Neunhöffer
 Anthon van der Neut
 George Neville-Neil

Misc/NEWS.d/next/Library/2025-11-22-20-30-00.gh-issue-101100.frksvr.rst

@@ -0,0 +1,5 @@
+Add a ``raise_exceptions`` keyword-only parameter to
+:func:`multiprocessing.set_forkserver_preload`. When set to ``True``,
+:exc:`ImportError` exceptions during module preloading will be raised instead
+of being silently ignored. Defaults to ``False`` for backward compatibility.
+Contributed by Nick Neumann.