Install & Compatibility
Where this runs
tested against v1.204.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 34.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.0s · import 0.000s · 35MB
34MB installed
● package 34MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Bucket
✓ from aws_cdk import aws_s3 as s3
from aws_cdk import core
✗ from aws_cdk_lib.aws_s3 import Bucket
Incorrect for CDK v1. This is the v2 import path. For v1, import `aws_s3` as a module and access `s3.Bucket`.
Stack
✓ from aws_cdk import core
✗ from aws_cdk_lib import Stack
Incorrect for CDK v1. This is the v2 import path. For v1, `Stack` is available under the `core` module, typically imported as `cdk.Stack`.
This quickstart demonstrates how to define a basic S3 bucket using `aws-cdk.aws-s3` in a Python CDK application. It sets up a minimal stack and creates an S3 bucket with a globally unique name using the AWS account ID. Remember that `cdk.App().synth()` is used to generate the CloudFormation template. To deploy, you would run `cdk deploy` after bootstrapping your AWS environment.
import os
from aws_cdk import ( # type: ignore
core as cdk,
aws_s3 as s3
)
class MyS3Stack(cdk.Stack):
def __init__(self, scope: cdk.Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Define an S3 bucket
# For production, consider adding specific bucket_name, versioned, encryption, and public access settings
# A removal_policy of RETAIN is the default for stateful resources like S3 buckets.
# If you want the bucket and its contents to be deleted with the stack, use RemovalPolicy.DESTROY and auto_delete_objects=True (see warnings).
s3.Bucket(self, "MyFirstS3Bucket",
versioned=False,
bucket_name=f"my-unique-bucket-{cdk.Aws.ACCOUNT_ID}", # Bucket names must be globally unique
removal_policy=cdk.RemovalPolicy.RETAIN, # Default for stateful resources
# auto_delete_objects=True # Use with caution and ONLY if removal_policy is DESTROY
)
app = cdk.App()
MyS3Stack(app, "MyS3Stack")
app.synth()
Debug
Known issues
breakingAWS CDK v1 is End-of-Support (EOS) as of June 1, 2023. This `aws-cdk.aws-s3` package is no longer maintained. Continued use may expose your applications to security vulnerabilities or compatibility issues with newer AWS features.fixMigrate your CDK application to AWS CDK v2. This involves changing package dependencies from individual `aws-cdk.aws-s3` and `aws-cdk.core` to a consolidated `aws-cdk-lib` package and updating import statements. Consult the official AWS CDK v2 migration guide for detailed steps.
affects: 1.x.x (all versions)
gotchaBy default, S3 buckets created with CDK (and CloudFormation) have a `removal_policy` of `RETAIN`. If you delete the CDK stack, the S3 bucket will NOT be deleted and will remain in your account, leading to potential resource leaks or conflicts if you try to recreate a bucket with the same name. Additionally, a non-empty bucket cannot be deleted by CloudFormation if `removal_policy` is `DESTROY` without `auto_delete_objects` enabled.fixTo ensure an S3 bucket is deleted with its stack (and its contents), set both `removal_policy=cdk.RemovalPolicy.DESTROY` AND `auto_delete_objects=True` when defining the `s3.Bucket` construct. Use this with extreme caution in production environments as it leads to irreversible data loss.
affects: 1.x.x (all versions)
gotchaYou might encounter 'Access Denied' errors when applying bucket policies, especially if the bucket already exists or if `BlockPublicAccess` is enabled. CloudFormation does not allow replacing or modifying bucket policies that were created outside its control.fixEnsure the IAM user/role deploying the stack has sufficient `PutBucketPolicy` permissions. If using an existing bucket, consider importing it into CDK or recreating it entirely within CDK control. If `block_public_access` is set (e.g., `s3.BlockPublicAccess.BLOCK_ALL`), this can interfere with custom bucket policies; temporarily disabling it, deploying, and re-enabling might be a workaround if truly necessary.
affects: 1.x.x (all versions)
gotchaIntermittent `CREATE_FAILED` errors for S3 Bucket Policies with 'Unable to retrieve Arn attribute for AWS::S3::Bucket, with error message Bucket not found'. This is a known CloudFormation dependency issue where the policy tries to access the bucket's ARN before it's fully provisioned.fixThis issue is often intermittent. Retrying the `cdk deploy` command typically resolves it. In some cases, deploying the bucket without a policy first, then adding the policy in a subsequent deployment, can work.
affects: 1.x.x (all versions)
Errors
Common errors & fixes
ImportError: cannot import name 'core' from 'aws_cdk'
You are attempting to import `core` directly from `aws_cdk`, which is a common mistake when mixing CDK v1 and v2 import patterns, or if your virtual environment is not correctly set up for v1.
fixFor CDK v1, `core` should be imported as `import aws_cdk.core as cdk`. Ensure your `requirements.txt` specifies `aws-cdk.core` for v1. If you intended to use CDK v2, you should import `Stack` and other core modules directly from `aws_cdk_lib` (e.g., `from aws_cdk_lib import Stack, App`).
The bucket that you tried to delete is not empty
This occurs during `cdk destroy` if an S3 bucket is set with `removal_policy=cdk.RemovalPolicy.DESTROY` but still contains objects. AWS S3 prevents deletion of non-empty buckets.
fixTo allow CDK to delete the bucket and its contents, you must set both `removal_policy=cdk.RemovalPolicy.DESTROY` and `auto_delete_objects=True` when defining the `s3.Bucket` construct. Alternatively, manually empty the bucket before destroying the stack.
An error occurred (BucketAlreadyOwnedByYou) when calling the CreateBucket operation: Your bucket name is not unique and you already own a bucket with that name.
S3 bucket names must be globally unique across all AWS accounts, or at least unique within your account if `BucketAlreadyOwnedByYou` is seen. This error indicates you are trying to create a bucket with a name that already exists and is owned by your account (possibly from a previous failed deployment with `RETAIN` policy).
fixChoose a different, globally unique bucket name (e.g., by appending `cdk.Aws.ACCOUNT_ID` or a random suffix). If the bucket exists and is orphaned from a previous CDK deployment, manually delete it or import it into your current stack.
API: s3:PutBucketPolicy Access Denied
The IAM user or role deploying the CDK stack lacks the necessary `s3:PutBucketPolicy` permissions on the target S3 bucket, or there's a conflict with `BlockPublicAccess` settings.
fixGrant the deploying IAM entity `s3:PutBucketPolicy` permissions. Review the bucket's `block_public_access` settings; if `BlockPublicAccess.BLOCK_ALL` is set, it might prevent certain policy modifications. Ensure no conflicting explicit deny statements exist in other policies.
Upgrade
Version history
1.204.0latest on PyPI · released Jun 19, 2023
Audit
Dependencies
aws-cdk.corerequiredCore CDK functionalities like Stack and App are in this package for v1.
constructsrequiredFundamental library for defining construct trees.