boto3-stubs Type Annotations for AWS SDK for Python

Common errors

Warnings

Install

Install compatibility stale last tested: 2026-05-12

Imports

• Session

  import boto3; from boto3.session import Session

  boto3-stubs works by augmenting the existing boto3 imports with type information; explicit imports from mypy_boto3_SERVICE are typically only needed for direct type hints.

• S3Client
  wrong

  from boto3.client import S3Client

  correct

  from mypy_boto3_s3.client import S3Client

  For explicit type annotations of a client, import the client type from the specific `mypy_boto3_SERVICE` module.

• Bucket
  wrong

  from boto3.resource import Bucket

  correct

  from mypy_boto3_s3.service_resource import Bucket

  For explicit type annotations of a service resource, import the resource type from the specific `mypy_boto3_SERVICE` module.

Quickstart stale last tested: 2026-04-24

This quickstart demonstrates how to use `boto3-stubs` to add type annotations to `boto3` client calls. By installing `boto3-stubs` (or `boto3-stubs[s3]` for S3 specific stubs), type checkers like MyPy will understand the return types and argument types of `boto3.client('s3')`, and IDEs will provide better auto-completion. Explicitly importing `S3Client` from `mypy_boto3_s3.client` allows for clear type hinting of the client object itself.

import boto3
from mypy_boto3_s3.client import S3Client
import os

def list_s3_buckets(region_name: str = os.environ.get('AWS_REGION', 'us-east-1')) -> list[str]:
    """Lists S3 bucket names with type hints."""
    # boto3-stubs automatically provides type hints for client() and resource() calls
    s3_client: S3Client = boto3.client("s3", region_name=region_name)
    response = s3_client.list_buckets()
    bucket_names = [bucket['Name'] for bucket in response.get('Buckets', [])]
    return bucket_names

if __name__ == "__main__":
    print(f"S3 Buckets: {list_s3_buckets()}")