Type Annotations for awscrt

0.31.3 verified Tue May 12 auth: no python install: stale quickstart: stale

types-awscrt provides type annotations and code completion for the `awscrt` package, which offers Python 3 bindings for the AWS Common Runtime. It helps with static analysis and IDE support for `awscrt`'s native C libraries. The package version typically mirrors the `awscrt` version it provides types for. It is actively maintained as part of the `mypy_boto3_builder` project. [4, 7]

pip install types-awscrt

Common errors

error ModuleNotFoundError: No module named 'types_awscrt' ↓

cause `types-awscrt` is a type stub package for static analysis (e.g., mypy), not a runtime library, and should not be directly imported. The actual runtime library is `awscrt`.

fix

import awscrt

error error: Library "awscrt" has no type annotations set up. [misc] ↓

cause The `awscrt` package itself does not include type annotations. `mypy` requires separate stub files, provided by `types-awscrt`, to perform type checking for `awscrt`.

fix

pip install types-awscrt

error ImportError: cannot import name 'io' from 'types_awscrt' ↓

cause Type stub packages like `types-awscrt` provide type hints for `awscrt` but are not meant for direct runtime import. You should import actual components from the `awscrt` package.

fix

from awscrt import io

Warnings

breaking In `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] ↓

fix Ensure `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.

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] ↓

fix When 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]

gotcha On 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] ↓

fix Be 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.

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] ↓

fix Keep `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.

breaking The `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. ↓

fix Ensure 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.

gotcha The `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. ↓

fix Ensure `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.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - - 18.0M

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 1.5s - 19M

3.10 slim (glibc) - - - -

3.11 alpine (musl) wheel - - 19.9M

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 1.6s - 20M

3.11 slim (glibc) - - - -

3.12 alpine (musl) wheel - - 11.7M

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 1.4s - 12M

3.12 slim (glibc) - - - -

3.13 alpine (musl) wheel - - 11.5M

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 1.4s - 12M

3.13 slim (glibc) - - - -

3.9 alpine (musl) wheel - - 17.5M

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 1.8s - 18M

3.9 slim (glibc) - - - -

Imports

ClientBootstrap
```
from awscrt.io import ClientBootstrap
```
AwsCredentials
```
from awscrt.auth import AwsCredentials
```
S3Client
```
from awscrt.s3 import S3Client
```
EventLoopGroup
```
from awscrt.io import EventLoopGroup
```

Quickstart stale last tested: 2026-04-24

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.