Type annotations for boto3

1.42.85 · active · verified Thu Apr 09

types-boto3 provides comprehensive type annotations (stubs) for the boto3 library, enabling static type checkers like MyPy to validate usage of AWS services. It is generated by the mypy-boto3-builder project and is currently at version 1.42.85. New versions are released frequently, typically mirroring boto3 updates or adding builder improvements.

Warnings

breaking Python 3.8 support was removed for all `mypy-boto3-builder` generated packages, including `types-boto3`.
Fix: Upgrade to Python 3.9 or higher. For older Python versions, use an earlier version of `mypy-boto3-builder` (e.g., <8.12.0) or `types-boto3`.
breaking Some TypeDef names were changed for brevity or to resolve conflicts (e.g., `CreateDistributionRequestRequestTypeDef` to `CreateDistributionRequestTypeDef`, `CreateDistributionExtraRequestTypeDef` to `CreateDistributionRequestExtraTypeDef`).
Fix: Update your type annotations to use the new TypeDef names. Consult the `mypy-boto3-builder` release notes or generated stubs for specific changes.
breaking The `sms-voice` service stubs were removed and are no longer generated. Users should migrate to `pinpoint-sms-voice`.
Fix: Migrate your code and type annotations to use the `pinpoint-sms-voice` service instead. Install `types-boto3-pinpoint-sms-voice`.
gotcha Installing `types-boto3` will install stubs for *all* AWS services, leading to a larger installation size and more dependencies than often necessary.
Fix: Prefer installing specific service stubs (e.g., `pip install types-boto3-s3 types-boto3-ec2`) for better performance, smaller dependency trees, and faster type-checking.
gotcha Ensure `boto3` is installed alongside `types-boto3`. `types-boto3` only provides type hints and does not include the runtime library itself.
Fix: Always install `boto3` (`pip install boto3`) in addition to the type stubs.

Install

pip install types-boto3 Install all service stubs
pip install types-boto3-s3 types-boto3-ec2 Install specific service stubs (recommended)

Imports

S3Client
```
from types_boto3_s3.client import S3Client
```
Import specific client types from the service stub package.
Session
```
from boto3.session import Session
```
The Session type is part of boto3 itself and not usually in types-boto3 (except for some specific cases like aioboto3 session stubs).
BucketTypeDef
```
from types_boto3_s3.type_defs import BucketTypeDef
```
Import TypeDef dictionaries for specific service operations.

Quickstart

This example demonstrates how to type-hint a boto3 S3 client using `types-boto3-s3` stubs. The `TYPE_CHECKING` block ensures that stub imports are only processed by type checkers and don't introduce runtime dependencies.

import boto3
from typing import TYPE_CHECKING

# It's good practice to guard stub imports for runtime environments
if TYPE_CHECKING:
    from types_boto3_s3.client import S3Client
    from types_boto3_s3.type_defs import BucketTypeDef


def list_s3_buckets(client: "S3Client") -> list["BucketTypeDef"]:
    response = client.list_buckets()
    return response.get("Buckets", [])


if __name__ == "__main__":
    # In a real application, you'd configure credentials/region
    # via environment variables or ~/.aws/credentials
    s3_client: S3Client = boto3.client("s3")
    buckets = list_s3_buckets(s3_client)
    print(f"Found {len(buckets)} S3 buckets.")
    for bucket in buckets:
        print(f"- {bucket['Name']}")

view raw JSON →