Lazy Loader

0.5 verified Tue May 12 auth: no python install: verified

The `lazy-loader` library makes it easy to load Python subpackages and functions on demand. This utility is designed to help projects, especially in the scientific Python ecosystem, reduce startup time and memory usage by deferring module imports until the imported objects are actually accessed. It is actively maintained, currently at version 0.5, and sees regular updates to enhance functionality and fix bugs.

pip install lazy-loader

Common errors

error ModuleNotFoundError: No module named 'lazy-load' ↓

cause The user attempted to import the `lazy-loader` library using an incorrect package name. The correct package name is `lazy-loader` (installed via `pip install lazy-loader`), which is then imported as `lazy_loader` in Python code.

fix

First, ensure the library is installed with pip install lazy-loader. Then, in your Python code, use import lazy_loader or from lazy_loader import ....

error AttributeError: module 'your_module' has no attribute 'your_attribute' ↓

cause This error often occurs when a lazily loaded module is accessed prematurely in a multithreaded or concurrent environment before it has been fully initialized, leading to an incomplete module object. It can also stem from known race conditions in specific Python versions (e.g., Python 3.11 prior to 3.11.9 or 3.12 prior to 3.12.3).

fix

If encountering this in a multithreaded context, ensure proper synchronization around the first access of lazily loaded modules. For Python 3.11 or 3.12, upgrade to patch versions 3.11.9+ or 3.12.3+ respectively. During debugging or for problematic scenarios, setting the environment variable EAGER_IMPORT to "1" (e.g., EAGER_IMPORT=1 python your_script.py) can temporarily disable lazy loading to identify if it's the root cause.

error All lazy-loaded packages are imported at once (unexpected eager loading) ↓

cause This is a reported behavioral issue where `lazy-loader` might unexpectedly import all specified modules eagerly, even when only a subset or a missing module is accessed, thus defeating the performance benefits of lazy loading. This can also happen if `lazy_loader.load()` is used for a subpackage (e.g., `lazy_loader.load('parent_package.sub_package')`), which immediately imports the parent package.

fix

Review your lazy_loader configuration to ensure it's not inadvertently triggering eager loads. Avoid using lazy_loader.load('parent_package.sub_package') as it is discouraged and can cause the parent to load immediately. If this behavior persists despite correct configuration, check the official lazy-loader GitHub repository for known bugs and potential workarounds or updates. Setting EAGER_IMPORT='1' can help confirm if eager loading is indeed occurring.

Warnings

breaking The `subpackages` argument for `lazy.attach()` was removed in `lazy-loader` version 0.4. Attempting to use this argument will result in a `TypeError`. The previous recommendation for lazily loading subpackages using this argument is no longer valid. ↓

fix For `lazy-loader` versions 0.4 and later, do not use the `subpackages` argument with `lazy.attach()`. Instead, `lazy.attach(__name__, __file__)` should be used for the package itself. Subpackage lazy loading should be handled by explicitly defining `__getattr__` or `__dir__` to return submodules, or by using `lazy.load` within these functions. If you require the functionality of `subpackages` for `lazy.attach`, you would need to downgrade to `lazy-loader` version `0.3.x`.

breaking Users on specific patch versions of Python 3.11 and 3.12 may encounter a known race condition due to upstream Python bugs affecting `lazy-loader`'s functionality. ↓

fix Upgrade Python to version 3.11.9 or later, or 3.12.3 or later, to avoid these known race conditions.

gotcha Lazy loading can defer import errors until runtime, making early detection of missing dependencies or typos harder during development. For debugging, `lazy-loader` can be disabled. ↓

fix Set the `EAGER_IMPORT` environment variable to `1` (e.g., `EAGER_IMPORT=1 python your_script.py`) to force eager loading of all modules managed by `lazy-loader`. This allows import errors to surface immediately upon program startup.

gotcha When using the `require` argument in `lazy.load()` to specify version requirements (e.g., `lazy.load('numpy', require='numpy>=1.24')`), the requirement string must use the *package distribution name* (as found on PyPI), not necessarily the module import name. ↓

fix Ensure the package name in the `require` argument precisely matches the distribution name. For example, `pyyaml` is the distribution name for the `yaml` module.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.01s 18.6M

3.10 alpine (musl) - - 0.01s 18.4M

3.10 slim (glibc) wheel 1.6s 0.01s 19M

3.10 slim (glibc) - - 0.01s 19M

3.11 alpine (musl) wheel - 0.01s 20.5M

3.11 alpine (musl) - - 0.01s 20.3M

3.11 slim (glibc) wheel 1.7s 0.01s 21M

3.11 slim (glibc) - - 0.01s 21M

3.12 alpine (musl) wheel - 0.01s 12.4M

3.12 alpine (musl) - - 0.01s 12.2M

3.12 slim (glibc) wheel 1.5s 0.01s 13M

3.12 slim (glibc) - - 0.01s 13M

3.13 alpine (musl) wheel - 0.01s 12.1M

3.13 alpine (musl) - - 0.01s 11.8M

3.13 slim (glibc) wheel 1.5s 0.01s 13M

3.13 slim (glibc) - - 0.01s 12M

3.9 alpine (musl) wheel - 0.01s 18.1M

3.9 alpine (musl) - - 0.01s 17.9M

3.9 slim (glibc) wheel 1.8s 0.01s 19M

3.9 slim (glibc) - - 0.01s 18M

Imports

lazy.attach

import lazy_loader as lazy
__getattr__, __dir__, _ = lazy.attach(__name__, __file__, subpackages=['my_subpackage'])

Used within a package's `__init__.py` to lazily expose subpackages or attributes.

lazy.load
```
import lazy_loader as lazy
external_module = lazy.load('some_external_library')
```
Used to lazily import an entire external module. The module is only loaded when `external_module` is first accessed.

Quickstart last tested: 2026-04-24

This example demonstrates how to use `lazy.attach` within a package's `__init__.py` to lazily load submodules. The `heavy_module` is only imported (and its 'imported!' message printed) when one of its attributes is first accessed, not during the initial `import mypackage` statement. This is the primary use case for `lazy-loader` to improve package import times.

import lazy_loader as lazy
import os

# This would typically be in your package's __init__.py
# For demonstration, we simulate it.

# Define a dummy 'heavy_module' that prints when imported
# In a real scenario, this would be a separate file or external library
with open('heavy_module.py', 'w') as f:
    f.write("""print('heavy_module imported!')
def expensive_func():
    return 'Result from expensive_func'
""")

# Create a dummy package directory and __init__.py
os.makedirs('mypackage', exist_ok=True)
with open('mypackage/__init__.py', 'w') as f:
    f.write("""import lazy_loader as lazy

__getattr__, __dir__, _ = lazy.attach(
    __name__, __file__,
    subpackages=[
        'heavy_module', # This will be lazily loaded
    ],
    attributes={
        'my_utility_func': ('some_utility_module', 'my_utility_func') # Example for external functions
    }
)

# If you also wanted to lazy load an external library directly (less common in __init__.py)
# external_lib = lazy.load('sys') # Example: lazily load 'sys'
""")

print("Before importing mypackage")
import mypackage
print("After importing mypackage (heavy_module not yet loaded)")

# Accessing an attribute of mypackage.heavy_module triggers its load
result = mypackage.heavy_module.expensive_func()
print(f"Accessed heavy_module: {result}")

# Clean up dummy files
os.remove('heavy_module.py')
os.remove('mypackage/__init__.py')
os.rmdir('mypackage')