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 · 32.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.0s · import 0.000s · 33MB
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Queue
✓ from aws_cdk import aws_sqs as sqs
✗ from aws_cdk.aws_sqs import Queue
While technically functional, the idiomatic AWS CDK v1 pattern is to import submodules as aliases (e.g., `aws_sqs as sqs`) to maintain consistent namespace access across CDK modules and avoid direct symbol imports that can lead to clashes.
Duration
✓ import aws_cdk as cdk
Duration is part of the core CDK library and is commonly accessed via the 'cdk' alias (e.g., `cdk.Duration`).
This quickstart demonstrates how to define a basic Amazon SQS queue using the `aws-cdk-aws-sqs` library. It creates an `App` and a `Stack`, then instantiates an `sqs.Queue` with a specified visibility timeout and outputs its URL. Ensure your AWS credentials are configured in your environment or `~/.aws/credentials` for successful deployment (`cdk deploy`).
import aws_cdk as cdk
import aws_cdk.aws_sqs as sqs
import os
class MySqsStack(cdk.Stack):
def __init__(self, scope: cdk.App, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
# Define an SQS Queue
queue = sqs.Queue(
self, "MySimpleQueue",
visibility_timeout=cdk.Duration.seconds(300),
queue_name="MyApplicationQueue" # Optional: give it a specific name
)
# Output the queue URL
cdk.CfnOutput(
self, "QueueUrl",
value=queue.queue_url,
description="The URL of the SQS queue",
)
# For authentication, CDK usually relies on AWS CLI configuration
# or environment variables (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION).
# No explicit auth needed in code for basic synth.
app = cdk.App()
MySqsStack(app, "MySqsQueueStack",
env=cdk.Environment(
account=os.environ.get("CDK_DEFAULT_ACCOUNT"),
region=os.environ.get("CDK_DEFAULT_REGION")
)
)
app.synth()
Debug
Known issues
breakingMigrating from AWS CDK v1 (`aws-cdk-aws-sqs`) to v2 (`aws-cdk-lib.aws_sqs`) involves significant breaking changes, primarily around import paths and package structure. V2 consolidates all constructs into a single `aws-cdk-lib` package.fixRefer to the official AWS CDK v1 to v2 migration guide. Key changes include importing `from aws_cdk_lib import aws_sqs as sqs` instead of `from aws_cdk import aws_sqs as sqs`, and installing `aws-cdk-lib` and `constructs` instead of individual `aws-cdk.aws-*` packages.
affects: Users moving from v1.x to v2.x
gotchaBy default, SQS queues are encrypted with SQS-managed server-side encryption. If you require AWS KMS encryption with your own customer-managed key (CMK), you must explicitly configure the `encryption` and `encryption_master_key` properties.fixSet `encryption=sqs.QueueEncryption.KMS` and provide a `kms_master_key` (e.g., an `aws_kms.Key` construct or an imported key) to the `Queue` properties.
affects: All v1.x
gotchaMissing or misconfigured Dead-Letter Queues (DLQs) can lead to lost messages when message processing fails repeatedly. While optional, it's highly recommended for production queues.fixDefine a separate `sqs.Queue` for the DLQ and configure the main queue's `dead_letter_queue` property, specifying the target queue and `max_receive_count`.
affects: All v1.x
gotchaCDK automatically generates unique physical names for resources. If you need a specific, fixed queue name, set the `queue_name` property, but be aware of potential naming conflicts when deploying multiple instances or in shared accounts.fixUse the `queue_name='MySpecificQueueName'` property when creating the `sqs.Queue` construct. Be cautious of naming collisions in the same AWS account/region.
affects: All v1.x
Errors
Common errors & fixes
jsii.errors.JavaScriptError: Error: There are still resources remaining in the stack 'MySqsQueueStack'.
Attempting to `cdk destroy` a stack that contains SQS queues with messages still in them, or a queue that is configured with a dead-letter queue that also contains messages.
fixEmpty the SQS queue (and its associated DLQ if present) manually before attempting to destroy the stack again. For production, consider retaining queues or configuring deletion policies (`removal_policy=cdk.RemovalPolicy.RETAIN`) to avoid data loss.
jsii.errors.JavaScriptError: 'MyQueue' has no associated Dead-Letter Queue (DLQ). Messages that fail to process will be lost.
This is a warning during CDK synthesis (not a deployment error) indicating that a best practice for message durability and error handling has not been followed.
fixDefine a separate SQS queue (e.g., `sqs.Queue(self, 'MyDLQ')`) and assign it as the `dead_letter_queue` to your main queue, also specifying `max_receive_count` for retry logic, e.g., `dead_letter_queue={ 'queue': my_dlq, 'max_receive_count': 3 }`. AttributeError: 'Queue' object has no attribute 'queue_arn'
This error typically indicates a typo in accessing the attribute, or attempting to access a property that only becomes available after synthesis or specific context.
fixEnsure you are using the correct attribute name, which is `queue.queue_arn` (or `queue.queue_url`). These properties are typically resolved during synthesis, so direct access within the stack definition usually works as expected. If passing across stacks, ensure appropriate methods like `export_value` are used.
Upgrade
Version history
1.204.0latest on PyPI · released Jun 19, 2023
Audit
Dependencies
aws-cdk.corerequiredCore CDK library for application and stack definitions.
constructsrequiredBase class for all constructs in the CDK framework.
jsiirequiredUsed for cross-language interoperability in CDK.