Add lazy import filter

python · pablogsal · Feb 12, 2026 · Sep 16, 2025 · Sep 18, 2025 · Sep 18, 2025
commit de281fd89457f05607b7a20dfaa4b4ffa95292d2
@@ -88,6 +88,16 @@ PyAPI_FUNC(int) PyImport_AppendInittab(
     PyObject* (*initfunc)(void)
     );
 
+typedef enum  {
+    PyLazyImportsMode_Default,
+    PyLazyImportsMode_ForcedOff,
+    PyLazyImportsMode_ForcedOn,
+} PyImport_LazyImportsMode;
+
+PyAPI_FUNC(int) PyImport_SetLazyImports(PyImport_LazyImportsMode mode, PyObject *filter);
+
+PyAPI_FUNC(PyImport_LazyImportsMode) PyImport_LazyImportsEnabled(void);
+
 #ifndef Py_LIMITED_API
 #  define Py_CPYTHON_IMPORT_H
 #  include "cpython/import.h"

diff --git a/Include/internal/pycore_ceval.h b/Include/internal/pycore_ceval.h
@@ -298,7 +298,7 @@ PyAPI_FUNC(void) _PyEval_FormatExcUnbound(PyThreadState *tstate, PyCodeObject *c
 PyAPI_FUNC(void) _PyEval_FormatKwargsError(PyThreadState *tstate, PyObject *func, PyObject *kwargs);
 PyAPI_FUNC(PyObject *) _PyEval_ImportFrom(PyThreadState *, PyObject *, PyObject *);
 PyAPI_FUNC(PyObject *) _PyEval_LazyImportName(PyThreadState *tstate, PyObject *builtins, PyObject *globals, 
-            PyObject *locals, PyObject *name, PyObject *fromlist, PyObject *level);
+            PyObject *locals, PyObject *name, PyObject *fromlist, PyObject *level, int lazy);
 PyAPI_FUNC(PyObject *) _PyEval_LazyImportFrom(PyThreadState *tstate, PyObject *v, PyObject *name);
 PyAPI_FUNC(PyObject *) _PyEval_ImportName(PyThreadState *tstate, PyObject *builtins, PyObject *globals, PyObject *locals,
             PyObject *name, PyObject *fromlist, PyObject *level);

diff --git a/Include/internal/pycore_global_objects_fini_generated.h b/Include/internal/pycore_global_objects_fini_generated.h
diff --git a/Include/internal/pycore_global_strings.h b/Include/internal/pycore_global_strings.h
@@ -574,6 +574,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(last_type)
         STRUCT_FOR_ID(last_value)
         STRUCT_FOR_ID(latin1)
+        STRUCT_FOR_ID(lazy)
         STRUCT_FOR_ID(leaf_size)
         STRUCT_FOR_ID(legacy)
         STRUCT_FOR_ID(len)

diff --git a/Include/internal/pycore_interp_structs.h b/Include/internal/pycore_interp_structs.h
@@ -314,6 +314,8 @@ struct _import_state {
 #endif
     PyObject *import_func;
     PyObject *lazy_import_func;
+    int lazy_imports_mode;
+    PyObject *lazy_imports_filter;
     /* The global import lock. */
     _PyRecursiveMutex lock;
     /* diagnostic info in PyImport_ImportModuleLevelObject() */

diff --git a/Include/internal/pycore_runtime_init_generated.h b/Include/internal/pycore_runtime_init_generated.h
diff --git a/Include/internal/pycore_unicodeobject_generated.h b/Include/internal/pycore_unicodeobject_generated.h
diff --git a/Lib/importlib/__init__.py b/Lib/importlib/__init__.py
@@ -59,7 +59,7 @@
 
 from ._bootstrap import __import__
 
-from _imp import lazy_import
+from _imp import lazy_import, set_lazy_imports
 
 
 def invalidate_caches():

diff --git a/Lib/test/test_import/__init__.py b/Lib/test/test_import/__init__.py
@@ -2548,6 +2548,8 @@ def tearDown(self):
             if key.startswith('test.test_import.data.lazy_imports'):
                 del sys.modules[key]
 
+        importlib.set_lazy_imports(None, None)
+
     def test_basic_unused(self):
         try:
             import test.test_import.data.lazy_imports.basic_unused
@@ -2564,6 +2566,54 @@ def test_basic_used(self):
 
         self.assertTrue("test.test_import.data.lazy_imports.basic2" in sys.modules)
 
+    def test_global_off(self):
+        try:
+            import test.test_import.data.lazy_imports.global_off
+        except ImportError as e:
+            self.fail('lazy import failed')
+
+        self.assertTrue("test.test_import.data.lazy_imports.basic2" in sys.modules)
+
+    def test_global_on(self):
+        try:
+            import test.test_import.data.lazy_imports.global_on
+        except ImportError as e:
+            self.fail('lazy import failed')
+
+        self.assertFalse("test.test_import.data.lazy_imports.basic2" in sys.modules)
+
+    def test_global_filter(self):
+        try:
+            import test.test_import.data.lazy_imports.global_filter
+        except ImportError as e:
+            self.fail('lazy import failed')
+
+        self.assertTrue("test.test_import.data.lazy_imports.basic2" in sys.modules)
+
+    def test_global_filter_true(self):
+        try:
+            import test.test_import.data.lazy_imports.global_filter_true
+        except ImportError as e:
+            self.fail('lazy import failed')
+
+        self.assertFalse("test.test_import.data.lazy_imports.basic2" in sys.modules)
+
+    def test_global_filter_from(self):
+        try:
+            import test.test_import.data.lazy_imports.global_filter
+        except ImportError as e:
+            self.fail('lazy import failed')
+
+        self.assertTrue("test.test_import.data.lazy_imports.basic2" in sys.modules)
+
+    def test_global_filter_from_true(self):
+        try:
+            import test.test_import.data.lazy_imports.global_filter_true
+        except ImportError as e:
+            self.fail('lazy import failed')
+
+        self.assertFalse("test.test_import.data.lazy_imports.basic2" in sys.modules)
+
 
 class TestSinglePhaseSnapshot(ModuleSnapshot):
     """A representation of a single-phase init module for testing.

@@ -0,0 +1,10 @@
+import importlib
+
+def filter(module_name, imported_name, from_list):
+    assert module_name == __name__
+    assert imported_name == "test.test_import.data.lazy_imports.basic2"
+    return False
+
+importlib.set_lazy_imports(None, filter)
+
+lazy import test.test_import.data.lazy_imports.basic2 as basic2
@@ -0,0 +1,11 @@
+import importlib
+
+def filter(module_name, imported_name, from_list):
+    assert module_name == __name__
+    assert imported_name == "test.test_import.data.lazy_imports.basic2"
+    assert from_list == ['f']
+    return False
+
+importlib.set_lazy_imports(None, filter)
+
+lazy from import test.test_import.data.lazy_imports.basic2 import f
@@ -0,0 +1,11 @@
+import importlib
+
+def filter(module_name, imported_name, from_list):
+    assert module_name == __name__
+    assert imported_name == "test.test_import.data.lazy_imports.basic2"
+    assert from_list == ['f']
+    return True
+
+importlib.set_lazy_imports(None, filter)
+
+lazy from import test.test_import.data.lazy_imports.basic2 import f
@@ -0,0 +1,10 @@
+import importlib
+
+def filter(module_name, imported_name, from_list):
+    assert module_name == __name__
+    assert imported_name == "test.test_import.data.lazy_imports.basic2"
+    return True
+
+importlib.set_lazy_imports(None, filter)
+
+lazy import test.test_import.data.lazy_imports.basic2 as basic2
@@ -0,0 +1,5 @@
+import importlib
+
+importlib.set_lazy_imports(False)
+
+lazy import test.test_import.data.lazy_imports.basic2 as basic2
@@ -0,0 +1,5 @@
+import importlib
+
+importlib.set_lazy_imports(True)
+
+import test.test_import.data.lazy_imports.basic2 as basic2
@@ -2947,10 +2947,11 @@ dummy_func(
          inst(IMPORT_NAME, (level, fromlist -- res)) {
             PyObject *name = GETITEM(FRAME_CO_NAMES, oparg >> 2);
             PyObject *res_o;
-            if (oparg & 0x01) {
+            if (!(oparg & 0x02)) {
                 res_o = _PyEval_LazyImportName(tstate, BUILTINS(), GLOBALS(), LOCALS(), name, 
                                 PyStackRef_AsPyObjectBorrow(fromlist),
-                                PyStackRef_AsPyObjectBorrow(level));
+                                PyStackRef_AsPyObjectBorrow(level),
+                                oparg & 0x01);
 
             } else {
                 res_o = _PyEval_ImportName(tstate, BUILTINS(), GLOBALS(), LOCALS(), name,

@@ -3027,8 +3027,25 @@ _PyEval_ImportName(PyThreadState *tstate, PyObject *builtins, PyObject *globals,
 
 PyObject *
 _PyEval_LazyImportName(PyThreadState *tstate, PyObject *builtins, PyObject *globals,
-            PyObject *locals, PyObject *name, PyObject *fromlist, PyObject *level)
+            PyObject *locals, PyObject *name, PyObject *fromlist, PyObject *level, int lazy)
 {
+    // Check if global policy overrides the local syntax
+    switch (PyImport_LazyImportsEnabled()) {
+        case PyLazyImportsMode_ForcedOff:
+            lazy = 0;
+            break;
+        case PyLazyImportsMode_ForcedOn:
+            lazy = 1;
+            break;
+        case PyLazyImportsMode_Default:
+            break;
+    }
+
+    if (!lazy) {
+        // Not a lazy import or lazy imports are disabled, fallback to the regular import
+        return _PyEval_ImportName(tstate, builtins, globals, locals, name, fromlist, level);
+    }
+
     PyObject *import_func;
     if (PyMapping_GetOptionalItem(builtins, &_Py_ID(__lazy_import__), &import_func) < 0) {
         return NULL;

diff --git a/Python/clinic/import.c.h b/Python/clinic/import.c.h
diff --git a/Python/executor_cases.c.h b/Python/executor_cases.c.h
diff --git a/Python/generated_cases.c.h b/Python/generated_cases.c.h