Implement PEP 810 – Explicit lazy imports

Linked PRs

pythongh-142349: Remove spurious Py_DECREF on borrowed ref in LOAD_GL…

gh-142349: Fix refcount corruption in lazy import specialization (#14…

pythongh-142349: Implement PEP 810 - Explicit lazy imports (python#14…

pythongh-142349: Fix build errors from PEP 810 (python#144726)

pythongh-142349: Fix refcount corruption in lazy import specialization (

pythongh-142349: Add CODEOWNERS for lazy imports

gh-142349: Add CODEOWNERS for lazy imports (#144840)

pythongh-142349: Fix ast.unparse for lazy import statements

pythongh-142349: Move all lazy-imports-by-hand to use the new lazy ke…

gh-142349: Fix ast.unparse for lazy import statements (#144893)

Should __lazy_import__ ignore sys.set_lazy_imports("none")?

Currently it does:

import sys
sys.set_lazy_imports("none")

lazy import annotationlib
typing = __lazy_import__("typing")

print(globals()["annotationlib"])  # <module 'annotationlib' from ...>
print(globals()["typing"])  # <lazy_import 'typing'>

A way to ignore this setting may actually be useful to handle circular imports, but I'm not sure if __lazy_import__ doing so is intentional.

Setting the filter currently crashes with __lazy_import__ so I couldn't check that interaction - #144851.

pythongh-142349: Implement PEP 810 - Explicit lazy imports (python#14…

pythongh-142349: Fix build errors from PEP 810 (python#144726)

pythongh-142349: Fix refcount corruption in lazy import specialization (

pythongh-142349: Add CODEOWNERS for lazy imports (python#144840)

pythongh-142349: Fix ast.unparse for lazy import statements (python#1…

@johnslavik

This is merged and in alpha 7.

Anything more to do here, or shall we close this issue and mark the PEP as Final?

Oh, one thing: __lazy_modules__ isn't documented yet. @johnslavik I think you might have had a PR for this to the lazycabal fork?

Oh, one thing: __lazy_modules__ isn't documented yet.

I'd add that sys.lazy_modules is also undocumented and needs general polishing (ref GH-145057 and GH-145059), and from some discussions I've had it is not clear if we'd like to keep it public or make it private.

@johnslavik I think you might have had a PR for this to the lazycabal fork?

I can't find it, but I'm happy to contribute more documentation as part of my interest in touching up lazy imports.

I was thinking of LazyImportsCabal#42.

pythongh-122575: pythongh-142349: fix sys.flags tuple size (it uninte…

gh-122575: gh-142349: fix sys.flags tuple size (it unintentionally in…

pythongh-142349: Implement PEP 810 - Explicit lazy imports (python#14…

pythongh-142349: Fix build errors from PEP 810 (python#144726)

pythongh-142349: Fix refcount corruption in lazy import specialization (

pythongh-142349: Add CODEOWNERS for lazy imports (python#144840)

pythongh-142349: Fix ast.unparse for lazy import statements (python#1…

pythongh-122575: pythongh-142349: fix sys.flags tuple size (it uninte…

pythongh-142349: Add `help("lazy")` support

gh-142349: Add `help("lazy")` support (#149886)

[3.15] gh-142349: Add `help("lazy")` support (GH-149886) (#149889)

sys.lazy_modules doesn't necessarily contain fully-qualified module names:

>>> lazy from math import floor
>>> import sys
>>> sys.lazy_modules
{..., 'math.floor'}

This doesn't match the docs or PEP. Is this intended?

Also, unlike regular import, lazy imports for non-modules work without from. This isn't clear from the PEP; is it intentional?

>>> lazy import math.floor
>>> math.floor
<built-in function floor>

>>> import math.floor
Traceback (most recent call last):
  File "<python-input-5>", line 1, in <module>
    import math.floor
ModuleNotFoundError: No module named 'math.floor'; 'math' is not a package

sys.lazy_modules doesn't necessarily contain fully-qualified module names:

lazy from math import floor
import sys
sys.lazy_modules
{..., 'math.floor'}
This doesn't match the docs or PEP. Is this intended?

Also, unlike regular import, lazy imports for non-modules work without from. This isn't clear from the PEP; is it intentional?

lazy import math.floor
math.floor

import math.floor
Traceback (most recent call last):
File "", line 1, in
import math.floor
ModuleNotFoundError: No module named 'math.floor'; 'math' is not a package

Being lazy there's no way to know what the names and their types are until the actual import happens so i feel like this is expected. The error appears on first use.

I expect most codebases adopting lazy have also adopted static analysis to catch this at build/push/CI time.

i feel like this is expected.

OK, so (for the first point) we should update the lazy_modules docs (and PEP, to match the implementation).

The error appears on first use.

The (second) point is that it does not appear at all.

update the lazy_modules docs (and PEP, to match the implementation).

I made these docs, how would you rephrase it?

I'm also unhappy with the current wording. Maybe "A set of strings capturing lazily imported modules or module members in the current interpreter. When a lazily imported module or module member is accessed for the first time and successfully resolved [reified?], its name is removed from this set.". WDYT?

I made GH-152622, let's iterate there.

I made these docs, how would you rephrase it?

The docs currently match the PEP, which should be changed to “accurately describes the implementation at the point where it is marked Final”. It's not about the docs.
Do you know why this wasn't implemented as specified?

Fully qualified module names would be useful as they could be passed to importlib.import_module to load eagerly. The current implementation looks like it's the legacy form for pkgutil.resolve_name -- is that right?

When a lazily imported module or module member is accessed for the first time and successfully resolved [reified?], its name is removed from this set.

That doesn't look right:

>>> lazy import typing
>>> globals()['typing']
<lazy_import 'typing'>
>>> import sys
>>> 'typing' in sys.lazy_modules
True
>>> globals()['typing'].resolve()
<module 'typing' from '/home/encukou/dev/cpython/Lib/typing.py'>
>>> 'typing' in sys.lazy_modules
True
>>> typing
<module 'typing' from '/home/encukou/dev/cpython/Lib/typing.py'>
>>> 'typing' in sys.lazy_modules
True

I think this is different depending on if the module has actually already been imported. If you're using the REPL then typing is already in sys.modules. If the module has already been imported then it still gets added but doesn't get removed.

Using threading instead, which isn't imported by the REPL.

>>> lazy import threading
>>> globals()['threading']
<lazy_import 'threading'>
>>> import sys
>>> 'threading' in sys.lazy_modules
True
>>> globals()['threading'].resolve()
<module 'threading' from '/home/david/.local/share/uv/python/cpython-3.15.0b3-linux-x86_64-gnu/lib/python3.15/threading.py'>
>>> 'threading' in sys.lazy_modules
False
>>> threading
<module 'threading' from '/home/david/.local/share/uv/python/cpython-3.15.0b3-linux-x86_64-gnu/lib/python3.15/threading.py'>
>>> threading in sys.lazy_modules
False

gh-142349: Clarify lazy import filters have positional-only parameters (

[3.15] gh-142349: Clarify lazy import filters have positional-only pa…

So, what is sys.lazy_modules meant to contain?

So, what is sys.lazy_modules meant to contain?

Thread continued on discuss.py

pythongh-142349: Clarify lazy import filters have positional-only par…

gh-142349: Clarify that sys.lazy_modules may contain extra items (GH-…

[3.15] gh-142349: Clarify that sys.lazy_modules may contain extra ite…

gh-142349: Document `LazyImportType.resolve()` method (GH-156936)

[3.15] gh-142349: Document `LazyImportType.resolve()` method (GH-156936…

pythongh-142349: Clarify that sys.lazy_modules may contain extra items (

pythongh-142349: Document `LazyImportType.resolve()` method (pythonGH…

gh-142349: Simplify lazy import resolution (#158282)

[3.15] gh-142349: Simplify lazy import resolution (GH-158282) (#158569)

gh-142349: Update lazy import comments in whatsnew (#158651)

[3.15] gh-142349: Update lazy import comments in whatsnew (GH-158651) (…

[3.15] pythongh-142349: Simplify lazy import resolution (pythonGH-158282

[3.15] pythongh-142349: Clarify that sys.lazy_modules may contain ext…

[3.15] pythongh-142349: Document `LazyImportType.resolve()` method (p…

gh-142349: Update lazy imports C API and sys.flags documentation (#15…

[3.15] gh-142349: Update lazy imports C API and sys.flags documentati…

Python 3.15 has been released with lazy imports! Thanks everyone!

Navigation Menu

Repository navigation

Implement PEP 810 – Explicit lazy imports #142349

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Implement PEP 810 – Explicit lazy imports #142349

Description

Linked PRs

Activity

DavidCEllis commented on Feb 17, 2026

hugovk commented on Mar 10, 2026

johnslavik commented on Mar 10, 2026

hugovk commented on Mar 10, 2026

encukou commented on Jun 29, 2026

gpshead commented on Jun 29, 2026

encukou commented on Jun 29, 2026

johnslavik commented on Jun 29, 2026

johnslavik commented on Jun 29, 2026

encukou commented on Jun 30, 2026

DavidCEllis commented on Jun 30, 2026

encukou commented on Jul 29, 2026

brittanyrey commented on Aug 3, 2026

hugovk commented on Oct 25, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions