cdk-lazy-import 1.0.0

Lazy-load aws_cdk submodules to speed up CDK synth

cdk-lazy-import

Speed up AWS CDK synth in Python by lazy-loading aws_cdk.aws_* service modules.

The problem

The AWS CDK for Python uses jsii to bridge between JavaScript and Python. When you import aws_cdk.aws_s3, jsii eagerly loads the module and all of its dependencies. A typical CDK app imports a handful of service modules, but each one pulls in shared machinery that touches all ~300 service packages. This means cdk synth spends several seconds just on imports before it even starts synthesizing your stack.

How it works

cdk-lazy-import installs a meta path finder that intercepts import aws_cdk.aws_* statements. Instead of loading the real module immediately, it returns a lightweight stub. The stub defers all work until your code actually accesses an attribute (like aws_s3.Bucket), at which point the real module is loaded transparently.

Non-service submodules (aws_cdk.cx_api, aws_cdk.pipelines, aws_cdk._jsii, etc.) are not intercepted and load normally. Deeper imports like aws_cdk.aws_s3.notifications are also handled normally once their parent resolves.

The result is byte-identical CloudFormation output with ~30-40% faster synth times in limited testing (~5.8s vs ~9.0s).

Installation

pip install cdk-lazy-import

That's it. The package includes a .pth file that activates the lazy-loading hook automatically at interpreter startup. No code changes, no configuration, no manual imports.

If aws-cdk-lib is not installed in the environment, the hook is a silent no-op.

Uninstallation

pip uninstall cdk-lazy-import

Removing the package removes the .pth file and restores default import behavior.

API

For most users, installing the package is sufficient. If you need manual control:

import cdk_lazy_import

# The .pth file calls this automatically, but you can call it yourself
# if you need to install the hook at a specific point. It's a no-op if
# the hook is already installed or aws_cdk is not available.
cdk_lazy_import.install()

Caveats

• Only aws_cdk.aws_* submodules are lazified. Other submodules load normally.
• The hook must be installed before any aws_cdk.aws_* imports. The .pth file ensures this happens at interpreter startup, but if something imports CDK modules before .pth files are processed (unusual), those modules won't be lazified.
• Performance gains depend on how many service modules your app uses. Apps that import nearly every service module will see less benefit.