mypy-boto3-s3 Type Annotations for AWS S3

raw JSON →
1.42.67 verified Tue May 12 auth: no python install: verified quickstart: verified

mypy-boto3-s3 provides comprehensive type annotations for the `boto3` AWS S3 service, enhancing type checking, code completion, and error detection in Python projects. It is generated by `mypy-boto3-builder`, ensuring compatibility with popular IDEs (VSCode, PyCharm) and type checkers (mypy, pyright). The library version typically mirrors the corresponding `boto3` version, indicating active and frequent releases in sync with AWS SDK updates.

pip install mypy-boto3-s3 boto3

Common errors

error ModuleNotFoundError: No module named 'mypy_boto3_s3' ↓
cause The `mypy-boto3-s3` package or `boto3-stubs[s3]` was not installed in your Python environment or is not accessible to your interpreter.
fix
Install the package using pip: python -m pip install mypy-boto3-s3 or python -m pip install 'boto3-stubs[s3]' if you prefer the meta-package approach.
error mypy: Cannot find implementation or library stub for module 'boto3' ↓
cause Mypy cannot find the type definitions for the `boto3` library, likely because `mypy-boto3-s3` or `boto3-stubs` is not installed, or your `mypy` configuration is incorrect (e.g., virtual environment not activated).
fix
Ensure mypy-boto3-s3 (or boto3-stubs[s3]) is installed in your environment (python -m pip install mypy-boto3-s3) and that mypy is run within the correct virtual environment. You might also need to explicitly configure mypy to follow imports or ensure your IDE uses the correct interpreter.
error AttributeError: 'dict' object has no attribute '...' (when accessing boto3 response attributes) ↓
cause This runtime error occurs when you attempt to access an attribute on a dictionary (a boto3 response) as if it were an object, indicating that static type checking failed to catch the issue because the response type was not correctly hinted or defaulted to `Any`.
fix
Explicitly import and use the appropriate TypeDef for the boto3 response from mypy_boto3_s3.type_defs. For example, response: ListBucketsOutputTypeDef = s3_client.list_buckets() will provide precise type checking for the dictionary structure.
error from mypy_boto3_s3.client import S3Client (used without if TYPE_CHECKING) ↓
cause Importing stub-only types directly at runtime without wrapping them in an `if TYPE_CHECKING:` block makes `mypy-boto3-s3` a runtime dependency, which can lead to `ModuleNotFoundError` in environments where stubs are not installed, or unnecessary overhead.
fix
Encapsulate type imports within if TYPE_CHECKING: blocks to ensure they are only processed by static type checkers and are ignored at runtime. 
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from mypy_boto3_s3.client import S3Client

def my_function(s3_client: S3Client):
    pass

Warnings

breaking Support for Python 3.8 was removed from `mypy-boto3-builder` version 8.12.0 onwards. This affects all generated stub packages, including `mypy-boto3-s3`. Projects on Python 3.8 will need to use an older version of the stubs or upgrade their Python interpreter. ↓
fix Upgrade to Python 3.9 or newer, or pin `mypy-boto3-s3` to a version compatible with Python 3.8 (e.g., <1.40.0, corresponding to builder <8.12.0).
breaking Type Definition (`TypeDef`) naming conventions changed in `mypy-boto3-builder` version 8.9.0. This can lead to shorter names for packed method arguments (e.g., `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`) and reordering of postfixes for conflicting names. Existing explicit imports of these `TypeDef`s will break. ↓
fix Update `TypeDef` import paths and names in your code to reflect the new conventions. Consult the specific service's documentation for the correct new names.
deprecated The original `mypy-boto3` package is considered legacy and users are encouraged to migrate to the `types-boto3` ecosystem. While `mypy-boto3-s3` is a specific service stub package, the overarching `mypy-boto3` project has transitioned to `types-boto3`. ↓
fix For new projects, prefer `types-boto3` and its service-specific extras (`boto3-stubs[s3]`). For existing projects, ensure your stub installation aligns with the `types-boto3` recommendations.
gotcha PyCharm users might experience slow performance and high CPU usage due to `Literal` overloads. This is a known issue (PY-40997) with PyCharm's type checker. ↓
fix Consider using `boto3-stubs-lite[s3]` for a more RAM-friendly option (requires explicit type annotations), or disable PyCharm's internal type checker and use an external tool like mypy or pyright instead.
gotcha As of `mypy-boto3-builder` 8.12.0, packages migrated to PEP 561 for distributing type information. While this generally improves automatic discovery, it is crucial that the stub package (`mypy-boto3-s3` or `boto3-stubs[s3]`) is installed in the same Python environment where `mypy` or other type checkers are run. ↓
fix Ensure `pip install mypy-boto3-s3` (or `boto3-stubs[s3]`) is run in the same virtual environment as your project and type checker. Mypy's `--no-site-packages` flag will disable this functionality if used.
gotcha Interacting with AWS services (e.g., listing S3 buckets) requires valid AWS credentials to be configured in the environment (e.g., via AWS environment variables, shared credential files, or IAM roles). Without credentials, `boto3` operations will fail with an `Unable to locate credentials` error. ↓
fix Ensure AWS credentials are properly configured in your environment. Refer to the AWS SDK documentation for Python for guidance on credential configuration.
gotcha The application failed to locate AWS credentials, which are required for authenticating with AWS services like S3. This is a common runtime configuration issue with `boto3` itself, independent of `mypy-boto3-s3` type stubs. ↓
fix Ensure AWS credentials are configured correctly in your environment. This can be achieved through environment variables (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`), shared credential files (`~/.aws/credentials`), IAM roles (for EC2 instances or other AWS services), or AWS Single Sign-On (SSO). Refer to the official `boto3` documentation for detailed credential configuration methods.

Install

pip install 'boto3-stubs[s3]' boto3

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk
3.10 alpine (musl) s3 wheel - 0.94s 53.7M
3.10 alpine (musl) mypy-boto3-s3 wheel - 0.90s 52.0M
3.10 alpine (musl) s3 - - 0.89s 53.5M
3.10 alpine (musl) mypy-boto3-s3 - - 0.89s 51.8M
3.10 slim (glibc) s3 wheel 10.5s 0.67s 54M
3.10 slim (glibc) mypy-boto3-s3 wheel 4.5s 0.68s 53M
3.10 slim (glibc) s3 - - 0.66s 54M
3.10 slim (glibc) mypy-boto3-s3 - - 0.66s 52M
3.11 alpine (musl) s3 wheel - 1.24s 56.8M
3.11 alpine (musl) mypy-boto3-s3 wheel - 1.31s 55.1M
3.11 alpine (musl) s3 - - 1.42s 56.6M
3.11 alpine (musl) mypy-boto3-s3 - - 1.47s 54.9M
3.11 slim (glibc) s3 wheel 6.1s 1.17s 57M
3.11 slim (glibc) mypy-boto3-s3 wheel 3.9s 1.12s 56M
3.11 slim (glibc) s3 - - 1.06s 57M
3.11 slim (glibc) mypy-boto3-s3 - - 1.09s 55M
3.12 alpine (musl) s3 wheel - 1.03s 48.0M
3.12 alpine (musl) mypy-boto3-s3 wheel - 1.02s 46.3M
3.12 alpine (musl) s3 - - 1.11s 47.8M
3.12 alpine (musl) mypy-boto3-s3 - - 1.09s 46.1M
3.12 slim (glibc) s3 wheel 4.4s 1.04s 49M
3.12 slim (glibc) mypy-boto3-s3 wheel 3.4s 1.17s 47M
3.12 slim (glibc) s3 - - 1.15s 48M
3.12 slim (glibc) mypy-boto3-s3 - - 1.08s 47M
3.13 alpine (musl) s3 wheel - 1.11s 47.7M
3.13 alpine (musl) mypy-boto3-s3 wheel - 1.10s 46.1M
3.13 alpine (musl) s3 - - 1.09s 47.4M
3.13 alpine (musl) mypy-boto3-s3 - - 1.06s 45.7M
3.13 slim (glibc) s3 wheel 4.1s 0.98s 48M
3.13 slim (glibc) mypy-boto3-s3 wheel 3.1s 1.01s 47M
3.13 slim (glibc) s3 - - 1.07s 48M
3.13 slim (glibc) mypy-boto3-s3 - - 1.10s 46M
3.9 alpine (musl) s3 wheel - 0.76s 53.1M
3.9 alpine (musl) mypy-boto3-s3 wheel - 0.78s 51.4M
3.9 alpine (musl) s3 - - 0.77s 53.0M
3.9 alpine (musl) mypy-boto3-s3 - - 0.79s 51.3M
3.9 slim (glibc) s3 wheel 12.0s 0.68s 54M
3.9 slim (glibc) mypy-boto3-s3 wheel 4.8s 0.69s 52M
3.9 slim (glibc) s3 - - 0.67s 54M
3.9 slim (glibc) mypy-boto3-s3 - - 0.69s 52M

Imports

Quickstart verified last tested: 2026-04-24

This quickstart demonstrates how to obtain type-hinted S3 clients and service resources using `mypy-boto3-s3`. Explicit type annotations for `boto3.client('s3')` and `boto3.resource('s3')` are provided by importing `S3Client` and `S3ServiceResource`. This enables full code completion and type checking for S3 operations.

import boto3
from mypy_boto3_s3.client import S3Client
from mypy_boto3_s3.service_resource import S3ServiceResource, Bucket

def get_s3_client() -> S3Client:
    """Returns a type-hinted S3 client."""
    # Type is automatically discovered by mypy and IDEs (if configured)
    return boto3.client("s3")

def get_s3_resource() -> S3ServiceResource:
    """Returns a type-hinted S3 service resource."""
    # Type is automatically discovered by mypy and IDEs (if configured)
    return boto3.resource("s3")

def get_s3_bucket(bucket_name: str) -> Bucket:
    """Returns a type-hinted S3 Bucket resource."""
    s3_resource: S3ServiceResource = boto3.resource("s3")
    return s3_resource.Bucket(bucket_name)

if __name__ == "__main__":
    s3_client = get_s3_client()
    print(f"S3 Client type: {type(s3_client)}")
    # Example usage: list buckets
    try:
        response = s3_client.list_buckets()
        print("Buckets:")
        for bucket in response.get("Buckets", []):
            print(f"  - {bucket['Name']}")
    except Exception as e:
        print(f"Error listing buckets: {e}")

    # Example resource usage
    # s3_resource = get_s3_resource()
    # my_bucket = get_s3_bucket("your-bucket-name")
    # print(f"Bucket name: {my_bucket.name}")
last verified Tue May 12
next check Fri Jun 26