PEP 810 – Explicit lazy imports

This PEP introduces syntax for lazy imports as an explicit language feature.
Lazy imports defer the loading and execution of a module until the first time
the imported name is used, in contrast to ‘normal’ imports, which eagerly load
and execute a module at the point of the import statement.

By allowing developers to mark individual imports as lazy with explicit syntax, Python programs
can reduce startup time, memory usage, and unnecessary work. This is
particularly beneficial for command-line tools, test suites, and applications
with large dependency graphs.

This proposal preserves full backwards compatibility: normal import statements
remain unchanged, and lazy imports are enabled only where explicitly requested.

The dominant convention in Python code is to place all imports at the module
level, typically at the beginning of the file. This avoids repetition, makes dependencies clear
and minimizes runtime overhead by only evaluating an import statement once
per module.

A major drawback with this approach is that importing the first
module for an execution of Python (the “main” module) often triggers an immediate
cascade of imports, and optimistically loads many dependencies that may never be used. The effect
is especially costly for command-line tools with multiple subcommands, where
even running the command with --help can load dozens of unnecessary modules and
take several seconds. This basic example demonstrates what must be loaded just to get helpful feedback to the user on how to run the program at
all. Inefficiently, the user incurs this overhead again when they figure out the command
they want and invoke the program “for real.”

A somewhat common way to delay imports is to move the imports into functions
(inline imports), but this practice requires more work to implement and maintain,
and can be subverted by a single inadvertent top-level import.
Additionally, it obfuscates the full set of dependencies for a module. Analysis
of the Python standard library shows that approximately 17% of all imports outside
tests (nearly 3500 total imports across 730 files) are already placed inside
functions or methods specifically to defer their execution. This
demonstrates that developers are already manually implementing lazy imports in
performance-sensitive code, but doing so requires scattering imports throughout
the codebase and makes the full dependency graph harder to understand at a
glance.

The standard library provides the LazyLoader class to solve some of these inefficiency
problems. It permits imports at the module level to work mostly like inline
imports do. Many scientific Python libraries have adopted a similar pattern, formalized
in SPEC 1. There’s also the
third-party lazy_loader package.
Imports used solely for static type checking are another source of potentially unneeded
imports, and there are similarly disparate approaches to minimizing the overhead.
The various approaches used here to defer or remove eager imports do not cover
all potential use-cases for a general lazy import mechanism. There is no clear standard,
and there are several drawbacks including runtime overhead in unexpected places,
or worse runtime introspection.

This proposal introduces syntax for lazy imports with a design that is local, explicit,
controlled, and granular. Each of these qualities is essential to making the feature
predictable and safe to use in practice.

The behavior is local: laziness applies only to the specific import marked
with the lazy keyword, and it does not cascade recursively into other
imports. This ensures that developers can reason about the effect of laziness
by looking only at the line of code in front of them, without worrying about
whether imported modules will themselves behave differently. A lazy import
is an isolated decision each time it is used, not a global shift in semantics.

The semantics are explicit. When a name is imported lazily, the binding
is created in the importing module immediately, but the target module is not
loaded until the first time the name is accessed. After this point, the binding
is indistinguishable from one created by a normal import. This clarity reduces
surprises and makes the feature accessible to developers who may not be
deeply familiar with Python’s import machinery.

Lazy imports are controlled, in the sense that deferred loading is only
triggered by the importing code itself. In the general case, a library will only
experience lazy imports if its own authors choose to mark them as such. This
avoids shifting responsibility onto downstream users and prevents accidental
surprises in library behavior. Since library authors typically manage their own
import subgraphs, they retain predictable control over when and how laziness is
applied.

The mechanism is also granular. It is introduced through explicit syntax on
individual imports, rather than a global flag or implicit setting. This allows
developers to adopt it incrementally, starting with the most
performance-sensitive areas of a codebase. As this feature is introduced to the
community, we want to make the experience of onboarding optional, progressive, and
adaptable to the needs of each project.

In addition to the new lazy import syntax, we also propose a way to
control lazy imports at the application level: globally disabling or
enabling lazy imports, and selectively disabling.
This global lazy imports flag is provided for debugging, testing, and experimentation,
and is not expected to be the common way to control lazy imports.

The design of lazy imports provides several concrete advantages:

• Command-line tools are often invoked directly by a user, so latency — in particular
  startup latency — is quite noticeable. These programs are also typically
  short-lived processes (contrasted with, e.g., a web server). Most conventions
  would have a CLI with multiple subcommands import every dependency up front,
  even if the user only requests tool --help (or tool subcommand --help).
  With lazy imports, only the code paths actually reached will import a module.
  This can reduce startup time by 50–70% in practice, providing a visceral improvement
  to a common user experience and improving Python’s competitiveness in domains
  where fast startup matters most.
• Type annotations frequently require imports that are never used at runtime.
  The common workaround is to wrap them in if TYPE_CHECKING: blocks .
  With lazy imports, annotation-only imports impose no runtime penalty, eliminating
  the need for such guards and making annotated codebases cleaner.
• Large applications often import thousands of modules, and each module creates
  function and type objects, incurring memory costs. In long-lived processes,
  this noticeably raises baseline memory usage. Lazy imports defer these costs
  until a module is needed, keeping unused subsystems unloaded. Memory savings of
  30–40% have been observed in real workloads.

The design of this proposal is centered on clarity, predictability, and ease of
adoption. Each decision was made to ensure that lazy imports provide tangible
benefits without introducing unnecessary complexity into the language or its
runtime.

It is also worth noting that while this PEP outlines one specific approach, we
list alternate implementation strategies for some of the core aspects and
semantics of the proposal. If the community expresses a strong preference for a
different technical path that still preserves the same core semantics or there
is fundamental disagreement over the specific option, we have included the
brainstorming we have already completed in preparation for this proposal as reference.

The choice to introduce a new lazy keyword reflects the need for explicit
syntax. Import behavior is too fundamental to be left implicit or hidden behind
global flags or environment variables. By marking laziness directly at the
import site, the intent is immediately visible to both readers and tools. This
avoids surprises, reduces the cognitive burden of reasoning about imports, and
keeps lazy import semantics in line with Python’s tradition of explicitness.

Another important decision is to represent lazy imports with proxy objects in
the module’s namespace, rather than by modifying dictionary lookup. Earlier
approaches experimented with embedding laziness into dictionaries, but this
blurred abstractions and risked affecting unrelated parts of the runtime. The
dictionary is a fundamental data structure in Python—literally every object is
built on top of dicts—and adding hooks to dictionaries would prevent critical
optimizations and complicate the entire runtime. The proxy approach is simpler:
it behaves like a placeholder until first use, at which point it resolves the
import and rebinds the name. From then on, the binding is indistinguishable
from a normal import. This makes the mechanism easy to explain and keeps the
rest of the interpreter unchanged.

Compatibility for library authors was also a key concern. Many maintainers need
a migration path that allows them to support both new and old versions of
Python at once. For this reason, the proposal includes the __lazy_modules__
global as a transitional mechanism. A module can declare which imports should
be treated as lazy (by listing the module names as strings), and on Python 3.15
or later those imports will become lazy automatically, as if they were imported
with the lazy keyword. On earlier versions the
declaration is ignored, leaving imports eager. This gives authors a practical
bridge until they can rely on the keyword as the canonical syntax.

Finally, the feature is designed to be adopted incrementally. Nothing changes
unless a developer explicitly opts in, and adoption can begin with just a few
imports in performance-sensitive areas. This mirrors the experience of gradual
typing in Python: a mechanism that can be introduced progressively, without
forcing projects to commit globally from day one. Notably, the adoption can also
be done from the “outside in”, permitting CLI authors to introduce lazy imports
and speed up user-facing tools, without requiring changes to every library the
tool might use.

By combining explicit syntax, a simple runtime model, a compatibility layer,
and gradual adoption, this proposal balances performance improvements with the
clarity and stability that Python users expect.

Lazy imports are opt-in. Existing programs continue to run unchanged unless
a project explicitly enables laziness (via lazy syntax, __lazy_modules__,
or an interpreter-wide switch).

There are no known security vulnerabilities introduced by lazy imports.

The new lazy keyword will be documented as part of the language standard.

As this feature is opt-in, new Python users should be able to continue using the
language as they are used to. For experienced developers, we expect them to leverage
lazy imports for the variety of benefits listed above (decreased latency, decreased
memory usage, etc) on a case-by-case basis. Developers interested in the performance
of their Python binary will likely leverage profiling to understand the import time
overhead in their codebase and mark the necessary imports as lazy. In addition,
developers can mark imports that will only be used for type annotations as lazy.

Below is guidance on how to best take advantage of lazy imports and how to avoid
incompatibilities:

• When adopting lazy imports, users should be aware that eliding an import until it is
  used will result in side effects not being executed. In turn, users should be wary of
  modules that rely on import time side effects. Perhaps the most common reliance on
  import side effects is the registry pattern, where population of some external
  registry happens implicitly during the importing of modules, often via
  decorators but sometimes implemented via metaclasses or __init_subclass__.
  Instead, registries of objects should be constructed via explicit discovery
  processes (e.g. a well-known function to call).

  # Problematic: Plugin registers itself on import
  # my_plugin.py
  from plugin_registry import register_plugin
  
  @register_plugin("MyPlugin")
  class MyPlugin:
      pass
  
  # In main code:
  lazy import my_plugin
  # Plugin NOT registered yet - module not loaded!
  
  # Better: Explicit discovery
  # plugin_registry.py
  def discover_plugins():
      from my_plugin import MyPlugin
      register_plugin(MyPlugin)
  
  # In main code:
  plugin_registry.discover_plugins()  # Explicit loading
  

• Always import needed submodules explicitly. It is not enough to rely on a different import
  to ensure a module has its submodules as attributes. Plainly, unless there is an
  explicit from . import bar in foo/__init__.py, always use import
foo.bar; foo.bar.Baz, not import foo; foo.bar.Baz. The latter only works
  (unreliably) because the attribute foo.bar is added as a side effect of
  foo.bar being imported somewhere else.
• Users who are moving imports into functions to improve startup time, should instead
  consider keeping them where they are but adding the lazy keyword. This allows
  them to keep dependencies clear and avoid the overhead of repeatedly re-resolving
  the import but will still speed up the program.

  # Before: Inline import (repeated overhead)
  def process_data(data):
      import json  # Re-resolved on every call
      return json.dumps(data)
  
  # After: Lazy import at module level
  lazy import json
  
  def process_data(data):
      return json.dumps(data)  # Loaded once on first call
  

• Avoid using wild card (star) imports, as those are always eager.

Q: How does this differ from the rejected PEP 690?

A: PEP 810 takes an explicit, opt-in approach instead of PEP 690’s implicit global approach. The key differences are:

• Explicit syntax: lazy import foo clearly marks which imports are lazy
• Local scope: Laziness only affects the specific import statement, not cascading to dependencies
• Simpler implementation: Uses proxy objects instead of modifying core dictionary behavior

Q: What happens when lazy imports encounter errors?

A: Import errors (ImportError, ModuleNotFoundError, syntax errors) are
deferred until first use of the lazy name. This is similar to moving an import
into a function. The error will occur with a clear traceback pointing to the
first access of the lazy object.

The implementation provides enhanced error reporting through exception chaining.
When a lazy import fails during reification, the original exception is preserved
and chained, showing both where the import was defined and where it was first
used:

Traceback (most recent call last):
  File "test.py", line 1, in 
    lazy import broken_module
ImportError: deferred import of 'broken_module' raised an exception during resolution

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "test.py", line 3, in 
    broken_module.foo()
    ^^^^^^^^^^^^^
  File "broken_module.py", line 2, in 
    1/0
ZeroDivisionError: division by zero

Q: How do lazy imports affect modules with import-time side effects?

A: Side effects are deferred until first use. This is generally desirable for performance, but may require code changes for modules that rely on import-time registration patterns. We recommend:

• Use explicit initialization functions instead of import-time side effects
• Call initialization functions explicitly when needed
• Avoid relying on import order for side effects

Q: Can I use lazy imports with from ... import ... statements?

A: Yes, as long as you don’t use from ... import *. Both lazy import foo
and lazy from foo import bar are supported. The bar name will be bound
to a lazy object that resolves to foo.bar on first use.

Q: Does lazy from module import Class load the entire module or just the class?

A: It loads the entire module, not just the class. This is because Python’s
import system always executes the complete module file—there’s no mechanism to
execute only part of a .py file. When you first access Class, Python:

1. Loads and executes the entire module.py file
2. Extracts the Class attribute from the resulting module object
3. Binds Class to the name in your namespace

This is identical to eager from module import Class behavior. The only difference
with lazy imports is that steps 1-3 happen on first use instead of at the import
statement.

# heavy_module.py
print("Loading heavy_module")  # This ALWAYS runs when module loads

class MyClass:
    pass

class UnusedClass:
    pass  # Also gets defined, even though we don't import it

# app.py
lazy from heavy_module import MyClass

print("Import statement done")  # heavy_module not loaded yet
obj = MyClass()                  # NOW "Loading heavy_module" prints
                                 # (and UnusedClass gets defined too)

Key point: Lazy imports defer when a module loads, not what gets loaded.
You cannot selectively load only parts of a module—Python’s import system doesn’t
support partial module execution.

Q: What about type annotations and TYPE_CHECKING imports?

A: Lazy imports eliminate the common need for TYPE_CHECKING guards. You can write:

lazy from collections.abc import Sequence, Mapping  # No runtime cost

def process(items: Sequence[str]) -> Mapping[str, int]:
    ...

Instead of:

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from collections.abc import Sequence, Mapping

def process(items: Sequence[str]) -> Mapping[str, int]:
    ...

Q: What’s the performance overhead of lazy imports?

A: The overhead is minimal:

• Zero overhead after first use thanks to the adaptive interpreter optimizing the slow path away.
• Small one-time cost to create the proxy object.
• Reification (first use) has the same cost as a regular import.
• No ongoing performance penalty unlike importlib.util.LazyLoader.

Benchmarking with the pyperformance suite shows the implementation is performance
neutral when lazy imports are not used.

Q: Can I mix lazy and eager imports of the same module?

A: Yes. If module foo is imported both lazily and eagerly in the same
program, the eager import takes precedence and both bindings resolve to the same
module object.

Q: How do I migrate existing code to use lazy imports?

A: Migration is incremental:

1. Identify slow-loading modules using profiling tools
2. Add lazy keyword to imports that aren’t needed immediately
3. Test that side-effect timing changes don’t break functionality
4. Use __lazy_modules__ for compatibility with older Python versions

Q: What about star imports (from module import *)?

A: Wild card (star) imports cannot be lazy – they remain eager. This is because the
set of names being imported cannot be determined without loading the module. Using the
lazy keyword with star imports will be a syntax error. If lazy imports are globally
enabled, star imports will still be eager.

Q: How do lazy imports interact with import hooks and custom loaders?

A: Import hooks and loaders work normally. When a lazy object is first used, the
standard import protocol runs, including any custom hooks or loaders that were
in place at reification time.

Q: What happens in multi-threaded environments?

A: Lazy import reification is thread-safe. Only one thread will perform the
actual import, and the binding is atomically updated. Other threads will see
either the lazy proxy or the final resolved object.

Q: Can I force reification of a lazy import without using it?

A: Yes, accessing a module’s __dict__ will reify all lazy objects in that
module. Individual lazy objects can be resolved by calling their get() method.

Q: What’s the difference between globals() and mod.__dict__ for lazy imports?

A: Calling globals() returns the module’s dictionary without reifying lazy
imports — you’ll see lazy proxy objects when accessing them through the returned
dictionary. However, accessing mod.__dict__ from external code reifies all lazy
imports in that module first. This design ensures:

# In your module:
lazy import json

g = globals()
print(type(g['json']))  #  - your problem

# From external code:
import sys
mod = sys.modules['your_module']
d = mod.__dict__
print(type(d['json']))  #  - reified for external access

This distinction means adding lazy imports and calling globals() is your
responsibility to manage, while external code accessing mod.__dict__ always
sees fully loaded modules.

Q: Why not use importlib.util.LazyLoader instead?

A: LazyLoader has significant limitations:

• Requires verbose setup code for each lazy import
• Has ongoing performance overhead on every attribute access
• Doesn’t work well with from ... import statements
• Less clear and standard than dedicated syntax

Q: Will this break tools like isort or black?

A: Tools will need updates to recognize the lazy keyword, but the changes
should be minimal since the import structure remains the same. The keyword
appears at the beginning, making it easy to parse.

Q: How do I know if a library is compatible with lazy imports?

A: Most libraries should work fine with lazy imports. Libraries that might have issues:

• Those with essential import-time side effects (registration, monkey-patching)
• Those that expect specific import ordering
• Those that modify global state during import

When in doubt, test lazy imports with your specific use cases.

Q: What happens if I globally enable lazy imports mode and a library doesn’t work correctly?

A: Note: This is an advanced feature. You can use the lazy imports filter to exclude
specific modules that are known to have problematic side effects:

import sys

def my_filter(importer, name, fromlist):
    # Don't lazily import modules known to have side effects
    if name in {'problematic_module', 'another_module'}:
        return False  # Import eagerly
    return True  # Allow lazy import

sys.set_lazy_imports_filter(my_filter)

The filter function receives the importer module name, the module being imported, and
the fromlist (if using from ... import). Returning False forces an eager import.

Alternatively, set the global mode to "disabled" via -X lazy_imports=disabled
to turn off all lazy imports for debugging.

Q: Can I use lazy imports inside functions?

A: No, the lazy keyword is only allowed at module level. For function-level
lazy loading, use traditional inline imports or move the import to module level
with lazy.

Q: What about forwards compatibility with older Python versions?

A: Use the __lazy_modules__ global for compatibility:

# Works on Python 3.15+ as lazy, eager on older versions
__lazy_modules__ = ['expensive_module', 'expensive_module_2']
import expensive_module
from expensive_module_2 import MyClass

The __lazy_modules__ attribute is a list of module name strings. When an import
statement is executed, Python checks if the module name being imported appears in
__lazy_modules__. If it does, the import is treated as if it had the lazy
keyword (becoming potentially lazy). On Python versions before 3.15 that don’t
support lazy imports, the __lazy_modules__ attribute is simply ignored and
imports proceed eagerly as normal.

This provides a migration path until you can rely on the lazy keyword. For
maximum predictability, it’s recommended to define __lazy_modules__ once,
before any imports. But as it is checked on each import, it can be modified between
import statements.

Q: How do explicit lazy imports interact with PEP-649/PEP-749

A: If an annotation is not stringified, it is an expression that is
evaluated at a later time. It will only be resolved if the annotation is
accessed. In the example below, the fake_typing module is only loaded
when the user inspects the __annotations__ dictionary. The
fake_typing module would also be loaded if the user uses
annotationlib.get_annotations() or getattr to access the annotations.

lazy from fake_typing import MyFakeType
def foo(x: MyFakeType):
  pass
print(foo.__annotations__)  # Triggers loading the fake_typing module

Q: How do lazy imports interact with dir(), getattr(), and module introspection?

A: Accessing lazy imports through normal attribute access or getattr() will trigger
reification. Calling dir() on a module will reify all lazy imports in that module
to ensure the directory listing is complete. This is similar to accessing mod.__dict__.

lazy import json

# Before any access
# json not in sys.modules

# Any of these trigger reification:
dumps_func = json.dumps
dumps_func = getattr(json, 'dumps')
dir(json)
# Now json is in sys.modules

Q: Do lazy imports work with circular imports?

A: Lazy imports don’t automatically solve circular import problems. If two modules
have a circular dependency, making the imports lazy might help only if the circular
reference isn’t accessed during module initialization. However, if either module
accesses the other during import time, you’ll still get an error.

Example that works (deferred access in functions):

# user_model.py
lazy import post_model

class User:
    def get_posts(self):
        # OK - post_model accessed inside function, not during import
        return post_model.Post.get_by_user(self.name)

# post_model.py
lazy import user_model

class Post:
    @staticmethod
    def get_by_user(username):
        return f"Posts by {username}"

This works because neither module accesses the other at module level—the access
happens later when get_posts() is called.

Example that fails (access during import):

# module_a.py
lazy import module_b

result = module_b.get_value()  # Error! Accessing during import

def func():
    return "A"

# module_b.py
lazy import module_a

result = module_a.func()  # Circular dependency error here

def get_value():
    return "B"

This fails because module_a tries to access module_b at import time, which
then tries to access module_a before it’s fully initialized.

The best practice is still to avoid circular imports in your code design.

Q: Will lazy imports affect the performance of my hot paths?

A: After first use, lazy imports have zero overhead thanks to the adaptive interpreter.
The interpreter specializes the bytecode (e.g., LOAD_GLOBAL becomes LOAD_GLOBAL_MODULE)
which eliminates the lazy check on subsequent accesses. This means once a lazy import
is reified, accessing it is just as fast as a normal import.

lazy import json

def use_json():
    return json.dumps({"test": 1})

# First call triggers reification
use_json()

# After 2-3 calls, bytecode is specialized
use_json()
use_json()

You can observe the specialization using dis.dis(use_json, adaptive=True):

=== Before specialization ===
LOAD_GLOBAL              0 (json)
LOAD_ATTR                2 (dumps)

=== After 3 calls (specialized) ===
LOAD_GLOBAL_MODULE       0 (json)
LOAD_ATTR_MODULE         2 (dumps)

The specialized LOAD_GLOBAL_MODULE and LOAD_ATTR_MODULE instructions are
optimized fast paths with no overhead for checking lazy imports.

Q: What about sys.modules? When does a lazy import appear there?

A: A lazily imported module does not appear in sys.modules until it’s reified
(first used). Once reified, it appears in sys.modules just like any eager import.

import sys
lazy import json

print('json' in sys.modules)  # False

result = json.dumps({"key": "value"})  # First use

print('json' in sys.modules)  # True

A reference implementation is available at:
https://github.com/LazyImportsCabal/cpython/tree/lazy

Here are some alternative design decisions that were considered during the development
of this PEP. While the current proposal represents what we believe to be the best balance
of simplicity, performance, and maintainability, these alternatives offer different
trade-offs that may be valuable for implementers to consider or for future refinements.

We would like to thank Paul Ganssle, Yury Selivanov, Łukasz Langa, Lysandros
Nikolaou, Pradyun Gedam, Mark Shannon, Hana Joo and the Python Google team, the
Python team(s) @ Meta, the Python @ HRT team, the Bloomberg Python team, the
Scientific Python community, everyone who participated in the initial discussion
of PEP 690, and many others who provided valuable feedback and insights that
helped shape this PEP.

This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive.