Install & Compatibility
Where this runs
tested against v3.6.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 1.579s · 304.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 19.0s · import 0.915s · 290MB
330MB installed
● package 330MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ec2
✓ from pulumi_awsx import ec2
✗ from pulumi_aws.ec2 import Vpc
Pulumi AWSX (pulumi_awsx) is a separate component library from the base AWS provider (pulumi_aws). Components are typically accessed via the top-level `pulumi_awsx` package.
ecs
✓ from pulumi_awsx import ecs
✗ from pulumi_aws.ecs import Cluster
Ensure you are importing from `pulumi_awsx` for the high-level components.
lb
✓ from pulumi_awsx import lb
✗ from pulumi_aws.lb import LoadBalancer
Use the `pulumi_awsx.lb` module for simplified load balancer components.
This quickstart demonstrates how to create a complete AWS Virtual Private Cloud (VPC) with public and private subnets across multiple availability zones using the `pulumi-awsx.ec2.Vpc` component. This component handles the creation of all necessary networking resources like internet gateways, NAT gateways, route tables, and subnet associations automatically. To run, ensure AWS credentials and region are configured for your Pulumi project.
import pulumi
import pulumi_awsx as awsx
import os
# Pulumi requires AWS credentials and a region to be configured.
# This can be done via environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION)
# or Pulumi configuration (pulumi config set aws:region us-east-1).
# For demonstration, ensure credentials are set up in your environment.
aws_region = os.environ.get('AWS_REGION', 'us-east-1') # Default to us-east-1 if not set
# Create an AWS VPC using pulumi-awsx.ec2.Vpc component.
# This component simplifies creating a VPC with public, private, and isolated subnets
# across multiple availability zones automatically.
my_vpc = awsx.ec2.Vpc("my-awsx-vpc",
cidr_block="10.0.0.0/16",
number_of_availability_zones=2, # Specify number of AZs
tags={
"Project": "PulumiAWSXQuickstart",
"ManagedBy": "Pulumi"
})
# Export the VPC ID and the IDs of its public and private subnets.
pulumi.export("vpc_id", my_vpc.vpc_id)
pulumi.export("public_subnet_ids", my_vpc.public_subnet_ids)
pulumi.export("private_subnet_ids", my_vpc.private_subnet_ids)
Debug
Known issues
breakingMajor breaking changes were introduced in `pulumi-awsx` v3.0.0, primarily due to its dependency on `pulumi-aws` v7.0.0. These changes affected resource input types and schemas across various components (e.g., `cloudtrail:Trail`, `ec2:Vpc`).fixReview the `pulumi-aws` v7.0.0 upgrade guide and corresponding `pulumi-awsx` changelog. Update your Pulumi code to match the new schema and input types. Use `pulumi preview` carefully to identify specific changes.
affects: 3.0.0 and newer
gotcha`pulumi-awsx` is built on `pulumi-aws`. Mismatched versions between `pulumi-awsx` and `pulumi-aws` (e.g., `pulumi-awsx` expecting `pulumi-aws` v7.x but `pulumi-aws` v6.x is installed) can lead to unexpected runtime errors or incorrect resource provisioning.fixAlways install the latest versions of both `pulumi-awsx` and `pulumi-aws` together. Regularly run `pip freeze` or check `requirements.txt` to ensure compatible dependency versions. Refer to the `pulumi-awsx` changelog for specific `pulumi-aws` version dependencies.
affects: All versions
gotchaPulumi automatically generates names for resources if not explicitly provided, often appending a random suffix for uniqueness. While convenient, this can lead to hard-to-track resource names in complex projects or unexpected resource recreation if the base name changes.fixFor critical or long-lived resources, explicitly provide `name` or `resource_name` arguments to ensure consistent, predictable naming. Be aware of naming conventions for resources that must be globally unique.
affects: All versions
deprecatedAs `pulumi-awsx` evolves, certain patterns or older resource properties might be deprecated in favor of newer, more robust abstractions. Using deprecated features can lead to warnings or unexpected behavior in future versions.fixPay attention to `pulumi up` warnings and documentation updates. Migrate code to use the recommended, up-to-date component properties and patterns as they are introduced.
affects: Across major and minor versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pulumi_awsx'
The `pulumi-awsx` library is not installed in your Python environment.
fixRun `pip install pulumi_awsx` to install the library.
AttributeError: module 'pulumi_awsx.ec2' has no attribute 'Vpc'
You might be trying to access a component that doesn't exist under that name, or there's a typo, or the component signature has changed in a major version upgrade.
fixDouble-check the Pulumi AWSX documentation for the correct component name and usage. Ensure your `pulumi-awsx` version is compatible with the code you are running. For VPC, it's `awsx.ec2.Vpc`.
pulumi:up failed with an unhandled exception: awsx:ec2/vpc:Vpc 'my-vpc' failed to update: Input 'cidrBlock' cannot be empty.
A required input property for the `Vpc` component, such as `cidr_block`, was not provided or was passed an empty/null value.
fixReview the component's required inputs in the Pulumi documentation and ensure all mandatory arguments are provided with valid values. For `Vpc`, ensure `cidr_block` is a valid CIDR string (e.g., '10.0.0.0/16').
TypeError: Expected argument of type pulumi.Input[str] but received argument of type pulumi.Input[Sequence[str]] for property 'advancedEventSelectors'
This error often indicates a type mismatch in resource inputs, commonly occurring after a major version upgrade of `pulumi-awsx` or `pulumi-aws`, where the expected type of a property has changed (e.g., from a single string to a list of strings).
fixConsult the changelog for the `pulumi-awsx` and `pulumi-aws` versions you are using, especially for `v3.0.0` or `v7.0.0` of `pulumi-aws`. Adjust the input argument to match the new expected type (e.g., wrap a single value in a list if it's now expecting a sequence).
Upgrade
Version history
3.6.0latest on PyPI · released Jun 5, 2026
Audit
Dependencies
pulumirequiredCore Pulumi engine required for all Pulumi programs.
pulumi-awsrequiredPulumi AWSX builds on top of the pulumi-aws provider; specific versions are often implicitly tied.