Install & Compatibility
Where this runs
tested against v0.36.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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ClientBootstrap
✓ from awscrt-stubs.io import ClientBootstrap
✗ from awscrt.io import ClientBootstrap
This quickstart demonstrates basic initialization of `awscrt` components. `types-awscrt` enhances this experience by providing static type checking and IDE auto-completion for `awscrt` objects and methods.
import os
import awscrt.io as io
import awscrt.auth as auth
import awscrt.s3 as s3 # Example usage
# Initialize the AWS Common Runtime's I/O and event loop
# types-awscrt provides type hints for these objects
event_loop_group: io.EventLoopGroup = io.EventLoopGroup()
host_resolver: io.DefaultHostResolver = io.DefaultHostResolver(event_loop_group)
bootstrap: io.ClientBootstrap = io.ClientBootstrap(event_loop_group, host_resolver)
# Example for AWS credentials (replace with actual logic, e.g., environment variables or assumed roles)
access_key_id = os.environ.get('AWS_ACCESS_KEY_ID', 'DUMMY_ACCESS_KEY')
secret_access_key = os.environ.get('AWS_SECRET_ACCESS_KEY', 'DUMMY_SECRET_KEY')
session_token = os.environ.get('AWS_SESSION_TOKEN', None) # Optional
credentials: auth.AwsCredentials = auth.AwsCredentials(
access_key_id=access_key_id,
secret_access_key=secret_access_key,
session_token=session_token
)
print(f"AWS CRT initialized. Credentials loaded (Access Key ID: {credentials.access_key_id}).")
# With types-awscrt installed, a type checker (like MyPy or Pyright) would validate the types above.
Debug
Known issues
breakingIn `awscrt` versions 0.28.2 and later, `awscrt.io.init_logging()` can only be called once per process. Subsequent calls will raise an `AWS_ERROR_INVALID_STATE` exception. This can impact test suites or applications that attempt to re-initialize logging. [14]fixEnsure `awscrt.io.init_logging()` is called only once in the application's lifecycle. Adjust tests to avoid re-initialization or reset logging state carefully if absolutely necessary.
affects: awscrt >= 0.28.2
gotcha`awscrt` uses background threads, which makes `os.fork()` unsafe on POSIX systems (excluding macOS) for Python versions 3.13 and earlier. Using `os.fork()` or the default `multiprocessing` start method ('fork') can lead to hangs or crashes in child processes. [8, 12]fixWhen using `multiprocessing`, explicitly set the start method to 'spawn' or 'forkserver' (e.g., `multiprocessing.set_start_method('spawn')`). If using `os.fork()` directly, ensure all CRT resources are released and all CRT threads are joined before forking. [8] affects: awscrt all versions, Python < 3.14 on POSIX (excluding macOS)
gotchaOn macOS, once a private key is used with a certificate in `awscrt`, that certificate-key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key from the Keychain and will ignore any private key passed in programmatically. [1, 8, 12]fixBe aware of this platform-specific behavior on macOS. If dynamic private key handling is critical, consider alternative approaches or ensure certificate-key pairs are managed appropriately within the Keychain.
affects: awscrt all versions on macOS
gotcha`types-awscrt` aims to have its version mirror the `awscrt` version it provides type stubs for. Significant discrepancies between `types-awscrt` and `awscrt` versions can lead to incorrect type hints, missing definitions, or type-checking errors if the underlying `awscrt` API has changed without a corresponding `types-awscrt` update. [4, 7]fixKeep `types-awscrt` and `awscrt` versions synchronized as closely as possible to ensure accurate type checking. Refer to the `types-awscrt` changelog or GitHub releases for specific `awscrt` versions supported.
affects: All versions
breakingThe `awscrt` module could not be found, indicating that the `awscrt` package is not installed or not accessible in the current Python environment. This prevents any `awscrt` functionality from being used.fixEnsure the `awscrt` package is installed in the environment by running `pip install awscrt` or by including it in your project's `requirements.txt` and installing dependencies.
affects: All versions
gotchaThe `awscrt` module was not found, indicating it is not installed in the current Python environment or is not accessible via the Python path. This error occurs when the Python interpreter cannot locate the package required by an `import` statement.fixEnsure `awscrt` is installed in the current Python environment using `pip install awscrt`. Verify that the Python interpreter being used has access to the installed package. Consider using a virtual environment (`python -m venv .venv` and `source .venv/bin/activate`) to manage dependencies and avoid conflicts with system-wide packages.
affects: All versions
Upgrade
Version history
0.36.2latest on PyPI · released Aug 12, 2026
Audit
Dependencies
awscrtoptionalRequired at runtime for the type stubs to be meaningful, as `types-awscrt` provides annotations for `awscrt`. The `awscrt` package itself requires Python >=3.8. [1, 8]
PythonrequiredRequires Python 3.8 or higher. [7, 8]