Install & Compatibility
Where this runs
tested against v15.5.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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
S3Client
✓ from aioboto3-stubs.s3.client import S3Client
✗ from aioboto3_stubs.s3.client import S3Client
This quickstart demonstrates how to integrate `types-aioboto3` for static type checking with an `aioboto3` S3 client. It shows how to import and apply `S3Client` and `BucketTypeDef` to enhance code clarity, enable IDE autocompletion, and catch potential errors at development time.
import aioboto3
import asyncio
from types_aioboto3_s3.client import S3Client
from types_aioboto3_s3.type_defs import BucketTypeDef
async def list_s3_buckets_typed():
session = aioboto3.Session()
async with session.client("s3") as client:
# Type hint the client to enable autocompletion and static checks
client: S3Client
response = await client.list_buckets()
# Type hint the list of buckets for better type safety
buckets: list[BucketTypeDef] = response.get("Buckets", [])
if not buckets:
print("No S3 buckets found or access denied.")
return
print("S3 Buckets:")
for bucket in buckets:
print(f" - {bucket['Name']}")
async def main():
# aioboto3 uses standard AWS credential chain (e.g., environment variables,
# ~/.aws/credentials, IAM roles). No hardcoded keys are needed here.
await list_s3_buckets_typed()
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingAs of mypy-boto3-builder 8.12.0 (which generates types-aioboto3), Python 3.8 is no longer supported for any generated packages. Users on Python 3.8 will encounter issues with newer versions.fixUpgrade your Python environment to version 3.9 or newer. Ensure your `pyproject.toml` or `setup.cfg` reflects `python_requires >=3.9`.
affects: mypy-boto3-builder >=8.12.0 (types-aioboto3 versions generated by it)
breakingService-specific TypeDef names for method arguments and conflicting names were changed in mypy-boto3-builder 8.9.0. For example, `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`, and `CreateDistributionExtraRequestTypeDef` became `CreateDistributionRequestExtraTypeDef`.fixUpdate type annotation references in your code to match the new naming conventions. Refer to the specific service stub documentation for updated TypeDef names.
affects: mypy-boto3-builder >=8.9.0 (types-aioboto3 versions generated by it)
deprecatedThe `sms-voice` service stubs were removed in mypy-boto3-builder 8.11.0. Users should migrate to `pinpoint-sms-voice` for related functionality.fixReplace references to `sms-voice` with `pinpoint-sms-voice` in your code and update imports and client calls accordingly (e.g., `session.client("pinpoint-sms-voice")` and `from types_aioboto3_pinpoint_sms_voice import PinpointSMSVoiceClient`). affects: mypy-boto3-builder >=8.11.0 (types-aioboto3 versions generated by it)
gotchaThis library provides type stubs for `aioboto3` and does not include the `aioboto3` runtime itself. It's solely for static type checking; you must install `aioboto3` separately for your application to run.fixEnsure `pip install aioboto3` is performed in your environment alongside `types-aioboto3`.
affects: all
gotchaEven if you install the `types-aioboto3` metapackage (which includes all service stubs), the type hints (e.g., Client classes, TypeDefs) must be imported from their respective service-specific sub-packages (e.g., `types_aioboto3_s3`).fixAlways use `from types_aioboto3_SERVICE.client import ServiceClient` and `from types_aioboto3_SERVICE.type_defs import ...` for specific service types.
affects: all
gotchaIt is recommended to keep the version of `types-aioboto3` (or its service-specific sub-packages) synchronized with your `aioboto3` runtime version to ensure accurate type hints, as stubs are generated for specific `aioboto3` versions and AWS API shapes.fixPeriodically update both `aioboto3` and `types-aioboto3` simultaneously, or pin their versions in your `requirements.txt` or `pyproject.toml` to prevent mismatches.
affects: all
Upgrade
Version history
15.5.0latest on PyPI · released Oct 31, 2025
Audit
Dependencies
aioboto3requiredProvides the runtime functionality for which these type stubs are generated. This library only provides types, not the runtime.