AWS CDK Assets (Deprecated)

1.204.0 · deprecated · verified Thu Apr 16

The `aws-cdk-assets` module (v1.x) for the AWS Cloud Development Kit (CDK) is deprecated. Its functionality, primarily for S3 and ECR assets, has been consolidated into specific, dedicated asset modules such as `aws-cdk.aws_s3_assets` and `aws-cdk.aws_ecr_assets` within CDK v1, or `aws_cdk_lib.aws_s3_assets` and `aws_cdk_lib.aws_ecr_assets` for CDK v2. It currently publishes alongside `aws-cdk` v1 releases, but its direct use is strongly discouraged.

Common errors

```
ModuleNotFoundError: No module named 'aws_cdk.aws_cdk_assets'
```
cause The `aws_cdk.aws_cdk_assets` module is deprecated and no longer part of the standard `aws-cdk` (v1) or `aws-cdk-lib` (v2) distributions.

fix Install `aws-cdk-lib` (for v2) or `aws-cdk.aws-s3-assets` (for v1) and update imports: `from aws_cdk_lib import aws_s3_assets` or `from aws_cdk import aws_s3_assets`.
```
AttributeError: module 'aws_cdk_lib.aws_s3' has no attribute 'Asset'
```
cause You are trying to import `Asset` from a general service module (`aws_s3`) instead of the dedicated assets module.

fix Import `Asset` (or `DockerImageAsset`) from the specific assets module: `from aws_cdk_lib import aws_s3_assets` then use `s3_assets.Asset(...)`.
```
jsii.errors.JavaScriptError: In 'new @aws-cdk/assets.Asset()': Path '<path>' does not exist.
```
cause The asset path specified in the `Asset` construct does not exist relative to your `cdk.json` or the working directory where `cdk synth` is executed.

fix Ensure the `path` argument to `s3_assets.Asset` points to an existing directory or file. Use `os.path.join(os.getcwd(), 'your_dir')` for absolute paths if needed.

Warnings

breaking The `aws-cdk-assets` package is deprecated and should not be used. Its constructs are no longer maintained or actively developed under this specific package name.
Fix: Migrate to dedicated asset modules: `aws_cdk.aws_s3_assets` / `aws_cdk.aws_ecr_assets` for CDK v1, or `aws_cdk_lib.aws_s3_assets` / `aws_cdk_lib.aws_ecr_assets` for CDK v2.
gotcha Attempting to use `from aws_cdk.aws_cdk_assets import Asset` or similar imports will result in `ModuleNotFoundError` or `AttributeError` when using `aws-cdk-lib` (CDK v2) or recent versions of `aws-cdk.core` (CDK v1).
Fix: Update your imports to use `from aws_cdk_lib import aws_s3_assets` (CDK v2) or `from aws_cdk import aws_s3_assets` (CDK v1) and ensure `aws-cdk-lib` or `aws-cdk.aws-s3-assets` is installed.
deprecated Even though `aws-cdk-assets` might still be installable for legacy reasons, its API is no longer part of the standard `aws-cdk` or `aws-cdk-lib` structure, leading to compatibility issues.
Fix: Refactor your CDK code to use the modern asset handling patterns provided directly by `aws-cdk-lib` (v2) or specific `aws-cdk.<service-name>-assets` modules (v1).

Install

pip install aws-cdk-assets Deprecated Installation
pip install aws-cdk-lib Recommended for CDK v2+
pip install aws-cdk.core aws-cdk.aws-s3-assets Recommended for CDK v1 (specific asset types)

Imports

Asset
wrong:
```
from aws_cdk.aws_cdk_assets import Asset
```
correct:
```
from aws_cdk_lib import aws_s3_assets
```
The `aws-cdk-assets` package is deprecated. For CDK v1, use specific modules like `aws_cdk.aws_s3_assets` or `aws_cdk.aws_ecr_assets`. For CDK v2+, use `aws_cdk_lib.aws_s3_assets` or `aws_cdk_lib.aws_ecr_assets`.
DockerImageAsset
wrong:
```
from aws_cdk.aws_cdk_assets import DockerImageAsset
```
correct:
```
from aws_cdk_lib import aws_ecr_assets
```
Docker assets are now found in dedicated modules (e.g., `aws_cdk_lib.aws_ecr_assets`).

Quickstart

This quickstart demonstrates how to use the recommended pattern for S3 assets within AWS CDK (v2+). Instead of `aws-cdk-assets`, you directly import and use `aws_s3_assets` from the `aws-cdk-lib` package. For CDK v1, replace `aws_cdk_lib` with `aws_cdk` and ensure you `pip install aws-cdk.aws-s3-assets`.

import os
from aws_cdk import (  # aws-cdk-lib for v2
    App, Stack,
    aws_s3_assets as s3_assets,
    aws_s3 as s3
)

class MyAssetStack(Stack):
    def __init__(self, scope: App, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Create a dummy directory for the asset
        asset_dir = 'my-asset-content'
        os.makedirs(asset_dir, exist_ok=True)
        with open(os.path.join(asset_dir, 'hello.txt'), 'w') as f:
            f.write('Hello, CDK Assets!')

        # Define an S3 Asset (CDK v2 example)
        my_asset = s3_assets.Asset(self, 'MyFileAsset',
            path=asset_dir
        )

        # Create an S3 Bucket and grant read access to the asset
        bucket = s3.Bucket(self, 'MyBucket',
            versioned=True  # Assets can be versioned
        )

        # Output the asset S3 path
        self.asset_s3_url = my_asset.s3_object_url
        print(f"Asset S3 URL: {self.asset_s3_url}")

        # Clean up dummy directory (optional)
        # import shutil
        # shutil.rmtree(asset_dir)

if __name__ == '__main__':
    app = App()
    stack = MyAssetStack(app, 'MyAssetStackExample')
    # Uncomment to synthesize for deployment
    # app.synth()

view raw JSON →