Install & Compatibility
Where this runs
tested against v4.2.2 · 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 · 380.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 17.9s · import 0.000s · 381MB
418MB installed
● package 418MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ECRDeployment
✓ from cdk_ecr_deployment import ECRDeployment
DockerImageName
✓ from cdk_ecr_deployment import DockerImageName
S3ArchiveName
✓ from cdk_ecr_deployment import S3ArchiveName
Used for deploying images from S3 tarballs.
To get started, create a CDK app (`cdk init app --language python`), then replace the content of your main stack file (e.g., `your_stack.py`) and your `app.py` with the code above. Remember to install `aws-cdk-lib`, `constructs`, and `cdk-ecr-deployment`. Ensure your AWS CLI is configured and your AWS environment is bootstrapped (`cdk bootstrap`) before deploying with `cdk deploy`.
import os
from aws_cdk import (
App,
Stack,
Environment,
aws_ecr as ecr,
Aws,
)
from constructs import Construct
from cdk_ecr_deployment import ECRDeployment, DockerImageName
class MyEcrDeploymentStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# 1. Define a destination ECR repository
destination_repo = ecr.Repository(self, "MyDestinationEcrRepo",
repository_name="my-app-image-destination",
image_scan_on_push=True,
image_tag_mutability=ecr.TagMutability.MUTABLE
)
# 2. Deploy a Docker image from Docker Hub (e.g., 'nginx:latest') to the ECR repository.
# Ensure your AWS credentials are configured (e.g., via AWS CLI) and your
# CDK environment is bootstrapped (run 'cdk bootstrap' once per account/region).
ECRDeployment(self, "DeployPublicNginxImage",
src=DockerImageName("nginx:latest"),
dest=DockerImageName(f"{Aws.ACCOUNT_ID}.dkr.ecr.{Aws.REGION}.amazonaws.com/{destination_repo.repository_name}:latest"),
)
app = App()
MyEcrDeploymentStack(app, "CdkEcrDeploymentExampleStack",
env=Environment(account=os.getenv('CDK_DEFAULT_ACCOUNT'), region=os.getenv('CDK_DEFAULT_REGION')),
)
app.synth()
Debug
Known issues
breakingOlder major versions (e.g., v1, v2) of cdk-ecr-deployment are no longer supported. Users should migrate to version 4.x to ensure compatibility with AWS CDK v2 and receive updates and bug fixes.fixUpgrade to the latest `cdk-ecr-deployment` package (version 4.x) and ensure your AWS CDK dependencies are also updated to v2.x. (e.g., `pip install cdk-ecr-deployment~=4.2.0 aws-cdk-lib~=2.x constructs~=10.x`)
affects: <4.0.0
gotchaWhen copying images, especially from external registries, previous versions did not automatically retry on AWS ECR rate limit errors, which could lead to deployment failures for large numbers of images or frequent pushes.fixUpgrade to `cdk-ecr-deployment` version 4.1.3 or higher, which includes a fix to retry on rate limit errors. Consider increasing the Lambda memory if deploying very large images, as noted in the documentation.
affects: <4.1.3
gotchaErrors occurring within the custom resource Lambda function (which performs the actual image copying) may manifest in CloudFormation logs as a generic `Invalid PhysicalResourceId`. The true error details are typically found in the associated AWS CloudWatch Logs for the Lambda function.fixIf a deployment fails with `Invalid PhysicalResourceId`, navigate to AWS CloudWatch Logs for the `ECRDeployment`'s underlying Lambda function to inspect detailed error messages.
affects: All versions
gotchaAuthentication to public ECR registries (e.g., `public.ecr.aws`) was not natively supported or straightforward in versions prior to 4.2.0, potentially causing authentication failures.fixUpgrade to `cdk-ecr-deployment` version 4.2.0 or newer for built-in authentication support for `public.ecr.aws` destinations.
affects: <4.2.0
gotchaWhen sourcing images from private Docker registries, credentials stored in AWS Secrets Manager must adhere to specific formats: either plain text `username:password` or a JSON object `{"username":"<username>","password":"<password>"}`.fixEnsure your Secrets Manager secret for private registry authentication follows the required plain text or JSON format specified in the documentation.
affects: All versions
gotchaIf you are using `aws-cdk-lib.aws_ecr_assets.DockerImageAsset` as a source, the CDK only rebuilds and pushes the Docker image when its source hash changes. If changes within your Docker context (e.g., code changes not reflected in the `Dockerfile` or `.dockerignore`) do not alter this hash, the image may not be updated on deployment.fixTo force a rebuild, ensure that changes affect the Docker build context hash. A common workaround is to include a version file (e.g., `build-version.txt`) in your Docker context and `COPY` it in your `Dockerfile`, incrementing its content for each desired rebuild.
affects: All versions (when using DockerImageAsset)
Upgrade
Version history
4.2.16latest on PyPI · released Jun 10, 2026
Audit
Dependencies
pythonrequiredRequired Python interpreter version for the library.
aws-cdk-librequiredPeer dependency as this is an AWS CDK construct, essential for defining and deploying AWS infrastructure.
constructsrequiredCore peer dependency for all AWS CDK constructs.