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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 61.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 7.6s · import 0.000s · 62MB
64MB installed
● package 64MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
UserPool
✓ from aws_cdk import aws_cognito as cognito
# then use cognito.UserPool(...)
✗ from aws_cdk_aws_cognito import UserPool
CDK construct libraries are typically imported from the `aws_cdk` namespace, not directly from their PyPI package name. The `aws_cognito` alias is common practice.
UserPool
✓ from aws_cdk.aws_cognito import UserPool
✗ from aws_cdk_aws_cognito.aws_cognito import UserPool
Direct import of specific classes from the `aws_cdk.aws_cognito` module is also common.
This quickstart demonstrates how to define a basic AWS Cognito User Pool and a User Pool Client using `aws-cdk-aws-cognito` within an AWS CDK v1 application. It sets up email as a sign-in alias, requires email verification, and enforces a strong password policy. The User Pool ID and Client ID are exported as CloudFormation outputs.
import aws_cdk as cdk
from aws_cdk import aws_cognito as cognito
from constructs import Construct
class MyCognitoStack(cdk.Stack):
def __init__(self, scope: Construct, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
# Create an AWS Cognito User Pool
user_pool = cognito.UserPool(self, "MyApplicationUserPool",
user_pool_name="MyWebAppUsers",
sign_in_aliases=cognito.SignInAliases(email=True),
standard_attributes=cognito.StandardAttributes(
email=cognito.StandardAttribute(required=True, mutable=True)
),
auto_verify=cognito.AutoVerifiedAttrs.EMAIL,
password_policy=cognito.UserPoolPasswordPolicy(
min_length=8,
require_lowercase=True,
require_uppercase=True,
require_digits=True,
require_symbols=True
)
)
# Create a User Pool Client for web applications
user_pool_client = cognito.UserPoolClient(self, "MyWebAppClient",
user_pool=user_pool,
generate_secret=False, # Typically False for client-side applications
supported_identity_providers=[
cognito.UserPoolClientIdentityProvider.COGNITO
]
)
cdk.CfnOutput(self, "UserPoolIdOutput", value=user_pool.user_pool_id)
cdk.CfnOutput(self, "UserPoolClientIdOutput", value=user_pool_client.user_pool_client_id)
# Instantiate the CDK App and Stack
app = cdk.App()
MyCognitoStack(app, "MyCognitoV1Stack")
app.synth()
Debug
Known issues
breakingAWS CDK v1 (where this package resides) is no longer actively developed with new features. AWS CDK v2 consolidates all official construct libraries into a single `aws-cdk-lib` package. Projects should migrate to v2 for new features, bug fixes, and security updates.fixMigrate your CDK application to v2. Install `aws-cdk-lib` instead of individual service packages. Adjust imports from `from aws_cdk import aws_cognito` to `from aws_cdk import aws_cognito as cognito` (or similar for specific symbols from `aws_cdk.aws_cognito`). Refer to the official AWS CDK v1 to v2 migration guide.
affects: All versions of `aws-cdk-aws-cognito` (v1.x.x)
deprecatedIndividual `aws-cdk-aws-*` packages are functionally deprecated for new development. While existing v1 applications using them will continue to work, new applications should use `aws-cdk-lib`.fixStart new projects with `aws-cdk-lib` (AWS CDK v2). For existing v1 projects, plan a migration to v2 to leverage ongoing support and new features.
affects: All versions of `aws-cdk-aws-cognito` (v1.x.x)
gotchaDeploying Cognito resources often requires specific IAM permissions that might not be included in default CDK deployment roles, especially for custom attributes, lambda triggers, or advanced settings.fixEnsure the IAM user/role executing `cdk deploy` has sufficient permissions (e.g., `cognito-idp:*`, `iam:PassRole` for lambda triggers, etc.). Check CloudFormation event logs for specific permission errors. Consider granting `AdministratorAccess` temporarily for initial deployment and then narrowing down permissions.
affects: All versions
gotchaWhen integrating Lambda functions as Cognito User Pool triggers, the User Pool requires explicit permission to invoke the Lambda function. For custom Lambda resource policies, ensure the User Pool ARN is correctly configured.fixUse the `add_trigger` method on the `UserPool` construct, which automatically handles the necessary permissions. If manually configuring, ensure `lambda.CfnPermission` is created allowing `cognito-idp.amazonaws.com` to invoke the Lambda.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aws_cdk.aws_cognito'
The `aws-cdk-aws-cognito` package (for v1) or `aws-cdk-lib` (for v2) is not installed, or the Python environment is not configured correctly.
fixFor AWS CDK v1, run `pip install aws-cdk-aws-cognito`. For AWS CDK v2 (recommended for new projects), run `pip install aws-cdk-lib`.
AttributeError: module 'aws_cdk.aws_cognito' has no attribute 'UserPool'
This typically indicates a version mismatch where an older version of the `aws-cdk-aws-cognito` package is installed, or an incorrect import path (e.g., trying to import a v2 construct into a v1 environment or vice-versa).
fixVerify your `aws-cdk-aws-cognito` package version using `pip show aws-cdk-aws-cognito`. Ensure it's compatible with your CDK CLI version. If migrating to v2, ensure `aws-cdk-lib` is installed and imports are `from aws_cdk.aws_cognito import UserPool` or `import aws_cdk.aws_cognito as cognito`.
User: arn:aws:iam::xxxxxxxxxxxx:user/YourUser is not authorized to perform: cognito-idp:CreateUserPool on resource: arn:aws:cognito-idp:us-east-1:xxxxxxxxxxxx:userpool/*
The IAM user or role used to deploy the CDK stack lacks the necessary permissions to create or modify Cognito User Pool resources.
fixGrant the `cognito-idp:CreateUserPool`, `cognito-idp:UpdateUserPool`, `cognito-idp:DeleteUserPool` (and related `cognito-idp:*`) permissions to the IAM identity performing the `cdk deploy`. Ensure `iam:PassRole` is also present if using Lambda triggers.
Error: The stack named 'MyCognitoStack' is not in a 'REVIEW_IN_PROGRESS' state.
This is a generic CloudFormation error often seen when trying to update a stack that previously failed or was manually modified out-of-band, preventing CDK from applying changes.
fixManually delete the failed CloudFormation stack from the AWS Console if it's stuck, then retry `cdk deploy`. Alternatively, if the resource causing the issue can be identified, import it into the stack state if manual changes were made (more advanced).
Upgrade
Version history
1.204.0latest on PyPI · released Jun 19, 2023
Audit
Dependencies
aws-cdk.corerequiredCore AWS CDK constructs and runtime for v1.
constructsrequiredBase class for all CDK constructs.