Install & Compatibility
Where this runs
tested against v3.9.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.000s · 19.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
S3Client
✓ from types_aiobotocore_s3 import S3Client
✗ from types_aiobotocore_s3 import S3Client
This quickstart demonstrates how to use `aiobotocore` with `types-aiobotocore-s3` for type-hinted interaction with Amazon S3. Once `types-aiobotocore-s3` is installed, `aiobotocore` client objects automatically gain type information. For explicit annotations, the `S3Client` type can be imported from `types_aiobotocore_s3.client` within a `TYPE_CHECKING` block to avoid runtime dependency. The example lists all S3 buckets in a specified region.
import asyncio
from os import environ
from typing import TYPE_CHECKING
# Only import S3Client for type checking, not for runtime
if TYPE_CHECKING:
from types_aiobotocore_s3.client import S3Client
from aiobotocore.session import get_session
async def list_s3_buckets():
session = get_session()
async with session.create_client("s3", region_name="us-east-1") as client:
# The 'client' object is automatically typed as S3Client
# if types-aiobotocore-s3 is installed.
# Explicit annotation for clarity:
s3_client: S3Client = client
response = await s3_client.list_buckets()
for bucket in response.get("Buckets", []):
print(f"Bucket Name: {bucket['Name']}")
# Example of type-checked operation
# await s3_client.non_existent_method() # MyPy would flag this
if __name__ == "__main__":
# Set dummy credentials for quickstart if not already set
environ.setdefault('AWS_ACCESS_KEY_ID', 'testing')
environ.setdefault('AWS_SECRET_ACCESS_KEY', 'testing')
environ.setdefault('AWS_SECURITY_TOKEN', 'testing')
environ.setdefault('AWS_DEFAULT_REGION', 'us-east-1')
asyncio.run(list_s3_buckets())
Debug
Known issues
breakingSupport for Python 3.8 was removed in `mypy-boto3-builder` version 8.12.0. Users on Python 3.8 should use an older version of `types-aiobotocore-s3` or upgrade their Python interpreter.fixUpgrade Python to 3.9 or newer, or pin `types-aiobotocore-s3` to a version compatible with Python 3.8 (e.g., <3.0.0, which corresponds to builder versions <8.12.0).
affects: >=3.4.0 (for types-aiobotocore-s3), >=8.12.0 (for mypy-boto3-builder)
breakingTypeDef names for packed method arguments changed in `mypy-boto3-builder` 8.9.0, adopting shorter names. For example, `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`.fixIf you explicitly import or reference TypeDefs from the stub package, update their names according to the new conventions.
affects: >=2.17.0 (for types-aiobotocore-s3), >=8.9.0 (for mypy-boto3-builder)
breakingThe `mypy-boto3-builder` project migrated to PEP 561 package structure in version 8.12.0. While this primarily affects package distribution and discovery, it might impact custom build systems or environments that expect the older stub package layout.fixEnsure your packaging and type-checking tools are compatible with PEP 561 stub packages. Most modern tools should handle this automatically.
affects: >=3.4.0 (for types-aiobotocore-s3), >=8.12.0 (for mypy-boto3-builder)
gotchaThe `types-aiobotocore-s3` package provides static type annotations for `aiobotocore`. For your code to run, you must also install the `aiobotocore` library itself, and ensure its version is compatible with the type stubs.fixAlways install `aiobotocore` alongside `types-aiobotocore-s3` (e.g., `pip install aiobotocore types-aiobotocore-s3`). Refer to the `types-aiobotocore-s3` `pyproject.toml` for the exact `aiobotocore` version it targets.
affects: All versions
Upgrade
Version history
3.9.0latest on PyPI · released Aug 2, 2026
Audit
Dependencies
aiobotocorerequiredProvides the underlying asynchronous AWS client library for which these are type stubs.
typing_extensionsrequiredRequired for compatibility with older Python versions, though types-aiobotocore-s3 now requires Python >=3.9, it's still listed as a dependency in its pyproject.toml.