aioboto3 is an asynchronous wrapper for boto3, the Amazon Web Services (AWS) SDK for Python. It allows developers to interact with AWS services using Python's `async/await` syntax, leveraging the `aiobotocore` library for its asynchronous backend. This enables non-blocking I/O operations with AWS, ideal for modern async applications. The current version is 15.5.0, with frequent releases often aligned with updates to its underlying dependencies.
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
muslpy 3.10–3.950 runs
installs and imports cleanly · install 0.0s · import 1.224s · 76.4MB
glibcpy 3.10–3.950 runs
installs and imports cleanly · install 7.3s · import 1.118s · 79MB
77MB installed
● package 77MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Session
✓ from aioboto3 import Session
✗ import aioboto3; client = aioboto3.client('s3')
Top-level `aioboto3.client` and `aioboto3.resource` were removed in v9. You must create a Session first, then use `session.client()` or `session.resource()`.
This quickstart demonstrates creating an asynchronous DynamoDB resource, creating a table (if it doesn't exist), inserting an item, querying it, and finally deleting the table. Ensure your AWS credentials and default region are configured in your environment (e.g., via `~/.aws/credentials` or environment variables like `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`).
import asyncio
import os
from aioboto3 import Session
from boto3.dynamodb.conditions import Key
async def main():
aws_region = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')
session = Session()
async with session.resource('dynamodb', region_name=aws_region) as dynamodb_resource:
table_name = 'my_async_table'
# Check if table exists, create if not (simplified for quickstart)
try:
await dynamodb_resource.Table(table_name).wait_until_exists()
print(f"Table '{table_name}' already exists.")
except Exception:
print(f"Creating table '{table_name}'...")
table = await dynamodb_resource.create_table(
TableName=table_name,
KeySchema=[
{'AttributeName': 'pk', 'KeyType': 'HASH'}
],
AttributeDefinitions=[
{'AttributeName': 'pk', 'AttributeType': 'S'}
],
BillingMode='PAY_PER_REQUEST'
)
await table.wait_until_exists()
print(f"Table '{table_name}' created successfully.")
table = await dynamodb_resource.Table(table_name)
table = await dynamodb_resource.Table(table_name)
print("Putting item...")
await table.put_item(
Item={'pk': 'test1', 'data': 'async_data_value'}
)
print("Item put.")
print("Querying item...")
result = await table.query(
KeyConditionExpression=Key('pk').eq('test1')
)
print("Query result:", result['Items'])
# Clean up (optional, for demonstration)
print(f"Deleting table '{table_name}'...")
await table.delete()
await table.wait_until_not_exists()
print(f"Table '{table_name}' deleted.")
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
breakingBreaking Change in v9: Direct calls to `aioboto3.resource()` and `aioboto3.client()` are no longer available. You must first create a `Session` object and then use `session.client()` or `session.resource()`.fixReplace `aioboto3.client('service')` with `session = aioboto3.Session(); async with session.client('service') as client:` affects: >= 9.0.0
breakingBreaking Change in v9/v8.0.0+: `client` and `resource` methods (obtained from a session) must now be used as asynchronous context managers (`async with`). This change aligns with `aiobotocore` 1.0.1+ behavior.fixEnsure all `session.client()` and `session.resource()` calls are wrapped in an `async with` statement, e.g., `async with session.client('s3') as s3_client:`. affects: >= 8.0.0
breakingBreaking Change in v11: The `S3Transfer` configuration passed into S3 `upload_file` and `download_file` methods has been updated to match `boto3`'s behavior, which might require adjustments if you were passing custom transfer configurations.fixReview S3 `upload_file` and `download_file` calls for custom `S3Transfer` configurations and adapt them to the `boto3`-aligned structure.
affects: >= 11.0.0
gotchaService-specific resource objects (e.g., `s3.Bucket`, `dynamo_resource.Table`) must be `await`ed when instantiated, as their creation is an asynchronous operation.fixAlways use `await` when getting a specific resource object, e.g., `bucket = await s3_resource.Bucket('mybucket')` or `table = await dynamodb_resource.Table('my_table')`. affects: All versions where `resource` is an async context manager
gotchaFor long-running processes like web servers, directly using `async with session.client(...)` per request can introduce overhead. For persistent clients, an `AsyncExitStack` or similar pattern is recommended to manage the context manager lifecycle.fixFor persistent clients in web servers, manage client/resource lifecycle using `AsyncExitStack` (e.g., in FastAPI's startup/shutdown events) to ensure clients are opened once and properly closed.
affects: All versions
gotchaaioboto3 could not find AWS credentials. This often manifests as `botocore.exceptions.NoCredentialsError: Unable to locate credentials` when attempting to interact with AWS services.fixEnsure AWS credentials are correctly configured in your environment. This can be done via environment variables (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`), shared credential files (`~/.aws/credentials`), or IAM roles (for EC2 instances or ECS tasks).
affects: All versions
gotchaUnable to locate AWS credentials. Ensure your AWS credentials are configured via environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), shared credentials file (~/.aws/credentials), or IAM roles/profiles.fixConfigure AWS credentials in your environment. Refer to the AWS documentation on configuring the AWS CLI and SDKs for detailed instructions.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aioboto3'
The 'aioboto3' library is not installed in the Python environment.
AttributeError: 'ResourceCreatorContext' object has no attribute 'Table'
The 'resource' method in 'aioboto3' is asynchronous and needs to be awaited.
fixdynamodb = await aioboto3.Session().resource('dynamodb') AttributeError: module 'aiobotocore' has no attribute 'AioSession'
The 'AioSession' attribute is not present in the 'aiobotocore' module, possibly due to version incompatibility.
fixEnsure compatible versions of 'aioboto3' and 'aiobotocore' are installed, or downgrade 'aioboto3' to a version where 'AioSession' is available.
AttributeError: 'ClientCreatorContext' object has no attribute 'invoke_endpoint'
The 'client' method in 'aioboto3' is asynchronous and needs to be awaited.
fixsagemaker_client = await aioboto3.Session().client('sagemaker-runtime') RuntimeWarning: coroutine '...' was never awaited
An asynchronous function (coroutine) was called, but its execution was not properly initiated using the `await` keyword or by `asyncio.run()`, meaning the coroutine object was created but never executed.
fixEnsure all calls to `async` functions within an `async` context are prefixed with `await`. If calling from synchronous code, wrap the coroutine call with `asyncio.run()`.
Audit
Dependencies
boto3requiredThe core AWS SDK that aioboto3 wraps.
aiobotocorerequiredThe asynchronous backend for AWS interactions.
cryptographyoptionalRequired for S3 client-side encryption functionality.