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.915 runs
installs and imports cleanly · install 0.0s · import 1.032s · 80.3MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 7.7s · import 0.943s · 64MB
72MB installed
● package 72MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_session
✓ from aiobotocore.session import get_session
✗ import aiobotocore; aiobotocore.get_session(loop=loop)
Top-level aiobotocore.get_session(loop=...) is the old pre-1.0 pattern. The loop parameter was removed. Always import from aiobotocore.session.
AioSession
✓ from aiobotocore.session import AioSession
Use when you need to subclass or explicitly type the session object.
AioConfig
✓ from aiobotocore.config import AioConfig
Required to pass connector_args (keepalive_timeout, use_dns_cache, etc.) or to set the experimental httpx backend.
AIOHTTPSession
✓ from aiobotocore.httpsession import AIOHTTPSession
Default HTTP session class; import only needed when customising the session class directly.
HttpxSession
✓ from aiobotocore.httpxsession import HttpxSession
Experimental httpx backend. Pass via AioConfig(http_session_cls=HttpxSession). Not fully tested; some aiohttp features are unported.
ClientError
✓ import botocore.exceptions; botocore.exceptions.ClientError
Error types live in botocore, not aiobotocore. Always catch botocore.exceptions.ClientError for AWS API errors.
List S3 buckets using an async context-managed client with credentials from environment variables.
import asyncio
import os
from aiobotocore.session import get_session
import botocore.exceptions
async def main():
session = get_session()
async with session.create_client(
's3',
region_name='us-east-1',
aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', ''),
aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', ''),
) as client:
try:
response = await client.list_buckets()
for bucket in response.get('Buckets', []):
print(bucket['Name'])
except botocore.exceptions.ClientError as e:
print(f"AWS error: {e.response['Error']['Code']} - {e.response['Error']['Message']}")
except botocore.exceptions.NoCredentialsError:
print('No credentials found')
asyncio.run(main())
Debug
Known issues
breakingcreate_client() MUST be used as an async context manager (async with). Calling it without a context manager and manually closing is unreliable, and since v3.0.0 creating a new ClientSession after the client exits its context is explicitly forbidden and raises an error.fixAlways use: async with session.create_client('s3', ...) as client: ... affects: >=1.0.0
breakingThe aiobotocore[boto3] and aiobotocore[awscli] packaging extras were removed in v3.0.0. Installing them will raise a pip error about unknown extras.fixInstall separately: pip install aiobotocore boto3 or pip install aiobotocore awscli
affects: >=3.0.0
breakingCredential properties (credentials.access_key, credentials.secret_key, credentials.token) raise NotImplementedError because they do not trigger an async refresh cycle.fixUse the async method: frozen = await credentials.get_frozen_credentials()
affects: >=1.4.0
gotchaaiobotocore pins botocore to a narrow version range that changes with every release. Installing aiobotocore alongside boto3, awscli, s3fs, or moto frequently causes pip dependency conflicts because those packages independently pin botocore.fixPin all AWS-related packages together (aiobotocore, boto3, botocore) to a mutually compatible set. Check the aiobotocore release notes for the supported botocore range. Use a lockfile (pip-tools, poetry, uv) to resolve conflicts upfront.
affects: <3.0.0 worst; improved but still present in >=3.0.0
gotchaget_object() response Body must be consumed inside an async context manager. Reading Body outside of 'async with response["Body"] as stream:' can leave the underlying TCP connection dangling and cause connection pool exhaustion.fixasync with response['Body'] as stream:
data = await stream.read() affects: all
gotchaPaginators are async iterators in aiobotocore. You must use 'async for result in paginator.paginate(...):', NOT a regular 'for' loop. A regular for loop will not await pages and silently yields nothing or raises TypeError.fixpaginator = client.get_paginator('list_objects_v2')
async for page in paginator.paginate(Bucket='my-bucket'):
for obj in page.get('Contents', []):
print(obj['Key']) affects: all
deprecatedPassing the 'loop' parameter to get_session() is a legacy pattern from pre-asyncio.run() era and is no longer supported. Python's asyncio manages the event loop implicitly.fixUse get_session() with no arguments, and run coroutines with asyncio.run(main()).
affects: >=2.x
breakingAWS error: AuthorizationHeaderMalformed. This usually means that AWS credentials (Access Key ID and Secret Access Key) are not configured correctly or are missing in the environment where the code is running. Common causes include missing environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) or an improperly configured AWS credentials file (~/.aws/credentials).fixEnsure AWS credentials are properly configured in the execution environment. This can be done via environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) or by configuring an AWS credentials file. Verify that the credentials have the necessary permissions for the AWS service being accessed.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aiobotocore'
The 'aiobotocore' library is not installed in the Python environment.
fixInstall 'aiobotocore' using pip: 'pip install aiobotocore'.
AttributeError: module 'aiobotocore' has no attribute 'AioSession'
The 'AioSession' attribute does not exist in the 'aiobotocore' module.
fixUse 'aiobotocore.session.get_session()' to create a session instead.
AttributeError: 'ClientCreatorContext' object has no attribute 'send_message'
The 'create_client' method returns a coroutine that needs to be awaited.
fixAwait the 'create_client' coroutine: 'client = await session.create_client('sqs')'. aiobotocore==X.Y.Z requires botocore<A.B.C,>=D.E.F but botocore G.H.I was resolved
There is a version incompatibility between 'aiobotocore' and 'botocore' (or 'boto3'), often due to other installed packages requiring different 'botocore' versions.
fixUse a virtual environment to isolate dependencies and explicitly pin compatible versions of 'aiobotocore', 'botocore', and 'boto3' in your project's dependencies.
botocore.exceptions.NoCredentialsError: Unable to locate credentials
The aiobotocore client, inheriting from botocore, cannot find valid AWS credentials in the standard locations (environment variables, shared credentials file, IAM role).
fixEnsure AWS credentials are configured properly, typically via environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`), a shared credentials file (`~/.aws/credentials`), or an IAM role attached to the execution environment.
Upgrade
Version history
3.9.0latest on PyPI · released Aug 1, 2026
Audit
Dependencies
botocorerequiredCore AWS service model and signing logic; aiobotocore pins a narrow botocore range per release — mismatches with boto3 or awscli are the #1 install conflict
aiohttprequiredDefault async HTTP backend
wraptrequiredUsed internally for patching botocore internals
boto3optionalHigher-level AWS resource API; must be installed separately — aiobotocore[boto3] extra was removed in v3.0.0
httpxoptionalExperimental alternative HTTP backend via AioConfig(http_session_cls=aiobotocore.httpxsession.HttpxSession)
types-aiobotocoreoptionalType annotations for IDE completion and static analysis (Pylance, pyright, mypy)