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.
Install & Compatibility
Where this runs
tested against v1.43.5 · 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.032s · 53.9MB
glibcpy 3.10–3.950 runs
installs and imports cleanly · install 5.6s · import 0.914s · 54MB
52MB installed
● package 52MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
S3Client
✓ from mypy_boto3_s3.client import S3Client
✗ from boto3.s3.client import S3Client
The correct type annotation for a boto3 S3 client is provided by `mypy-boto3-s3`.
S3ServiceResource
✓ from mypy_boto3_s3.service_resource import S3ServiceResource
✗ from boto3.s3.service_resource import S3ServiceResource
The correct type annotation for a boto3 S3 service resource is provided by `mypy-boto3-s3`.
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}")
Debug
Known issues
breakingSupport 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.fixUpgrade 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).
affects: mypy-boto3-builder >= 8.12.0
breakingType 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.fixUpdate `TypeDef` import paths and names in your code to reflect the new conventions. Consult the specific service's documentation for the correct new names.
affects: mypy-boto3-builder >= 8.9.0
deprecatedThe 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`.fixFor 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.
affects: < 8.9.0 (for `mypy-boto3` itself)
gotchaPyCharm 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.fixConsider 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.
affects: All versions with PyCharm
gotchaAs 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.fixEnsure `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.
affects: mypy-boto3-builder >= 8.12.0
gotchaInteracting 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.fixEnsure AWS credentials are properly configured in your environment. Refer to the AWS SDK documentation for Python for guidance on credential configuration.
affects: All versions of `boto3` and `mypy-boto3-*` when interacting with AWS
gotchaThe 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.fixEnsure 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.
affects: All versions of `boto3` (and consequently any related stub packages like `mypy-boto3-s3`)
Audit
Dependencies
boto3requiredThis package provides type annotations for the boto3 library, so boto3 is required for runtime functionality.
typing-extensionsoptionalRequired for older Python versions to support newer typing features. Automatically managed by install_requires.