Install & Compatibility
Where this runs
tested against v2.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.95 runs
installs and imports cleanly · install 0.0s · import 0.048s · 22.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.040s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Policy
✓ from awacs.aws import Policy
Statement
✓ from awacs.aws import Statement
Principal
✓ from awacs.aws import Principal
Action
✓ from awacs.aws import Action
Allow
✓ from awacs.aws import Allow
ARN
✓ from awacs.iam import ARN
AssumeRole
✓ from awacs.sts import AssumeRole
get_service_principal
✓ from awacs.helpers.trust import get_service_principal
This quickstart demonstrates how to create a simple AWS IAM AssumeRole policy and an S3 read-only policy using AWACS. It shows how to import core components like `Policy`, `Statement`, `Principal`, `Action`, `Effect`, and specific service actions (`AssumeRole`, `GetObject`, `ListBucket`) to build policies that can then be converted to a JSON string for use with AWS services.
from awacs.aws import Action, Allow, Policy, Principal, Statement
from awacs.iam import ARN
from awacs.sts import AssumeRole
# Create a basic AssumeRole policy
policy = Policy(
Statement(
Effect=Allow,
Principal=Principal("AWS", ARN("arn:aws:iam::123456789012:root")),
Action=[AssumeRole],
)
)
# Convert the policy to JSON string
policy_json = policy.to_json()
print(policy_json)
# Example of an S3 read-only policy for a specific bucket
from awacs.s3 import GetObject, ListBucket
s3_read_policy = Policy(
Statement(
Effect=Allow,
Action=[ListBucket],
Resource=[ARN("arn:aws:s3:::my-example-bucket")]
),
Statement(
Effect=Allow,
Action=[GetObject],
Resource=[ARN("arn:aws:s3:::my-example-bucket/*")]
)
)
print(s3_read_policy.to_json())
Debug
Known issues
breakingVersion 2.0.0 of AWACS dropped support for Python 2.x. This was a major breaking change, requiring all users to migrate to Python 3.x.fixEnsure your project runs on Python 3.x. The current stable version of AWACS requires Python >=3.9.
affects: >=2.0.0
breakingThe minimum required Python version has been progressively increased. As of version 2.5.0, AWACS officially requires Python >=3.9. Users on Python 3.6, 3.7, or 3.8 will encounter compatibility issues when upgrading to recent AWACS versions.fixUpgrade your Python environment to 3.9 or newer before installing or upgrading to the latest AWACS versions.
affects: >=2.1.0 (for 3.6), >=2.5.0 (for 3.7, 3.8)
gotchaAWACS dynamically generates AWS action definitions by scraping AWS documentation. If you're using an older version of the library, it might not contain the definitions for newly released AWS services or actions. This can lead to missing action errors or incomplete policies.fixRegularly update `awacs` to the latest version (`pip install --upgrade awacs`) to ensure you have the most current AWS action definitions.
affects: <2.5.0
gotchaVersion 2.4.0 included fixes for `mypy` which addressed implicit `Optional` types. Users relying on strict type checking with older `awacs` versions (prior to 2.4.0) might have encountered type-hinting related issues.fixUpgrade to `awacs` version 2.4.0 or newer for improved type-checking compatibility and reliability, especially in projects using `mypy` or similar static analysis tools.
affects: <2.4.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'awacs'
The 'awacs' library is not installed in the Python environment.
fixInstall the 'awacs' library using pip: 'pip install awacs'.
ImportError: cannot import name 'Policy' from 'awacs.aws'
The 'Policy' class has been deprecated in favor of 'PolicyDocument' in the 'awacs.aws' module.
fixReplace 'from awacs.aws import Policy' with 'from awacs.aws import PolicyDocument'.
AttributeError: module 'awacs' has no attribute 's3'
The 's3' module is not directly under 'awacs'; it should be imported from 'awacs.s3'.
fixUse 'from awacs.s3 import ARN' to import the 'ARN' class from the 's3' module.
TypeError: 'Statement' object is not iterable
The 'Statement' object is being used incorrectly, possibly by attempting to iterate over it.
fixEnsure that the 'Statement' object is correctly instantiated and used as a single object, not as an iterable.
ValueError: Invalid action 's3:*' specified
The action 's3:*' is not recognized, possibly due to incorrect formatting or an outdated action name.
fixVerify the action name against the latest AWS IAM documentation and ensure it is correctly formatted.
Upgrade
Version history
2.6.0latest on PyPI · released Jun 7, 2026
Audit
Dependencies
No dependency data recorded yet.