Install & Compatibility
Where this runs
tested against v1.43.66 · 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.95 runs
installs and imports cleanly · install 0.0s · import 1.046s · 52.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.9s · import 0.950s · 53MB
51MB installed
● package 51MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
S3Client
✓ from types_boto3_s3.client import S3Client
For type-hinting the S3 client returned by `boto3.client('s3')`.
S3ServiceResource
✓ from types_boto3_s3.service_resource import S3ServiceResource
For type-hinting the S3 service resource returned by `boto3.resource('s3')`.
ListBucketsOutputTypeDef
✓ from types_boto3_s3.type_defs import ListBucketsOutputTypeDef
For type-hinting the response structure of `s3_client.list_buckets()`.
This quickstart demonstrates how to use `types-boto3-s3` to add type hints to a `boto3` S3 client. The `TYPE_CHECKING` guard ensures that the type stubs are only imported during static analysis, preventing unnecessary runtime dependencies. It initializes an S3 client and lists bucket names, with all relevant variables type-hinted for better code quality and IDE support.
import boto3
from typing import TYPE_CHECKING
# Only import type stubs during type checking to avoid runtime dependency
if TYPE_CHECKING:
from types_boto3_s3.client import S3Client
from types_boto3_s3.type_defs import ListBucketsOutputTypeDef
def list_s3_bucket_names() -> list[str]:
# The actual boto3 client is used at runtime
s3_client: 'S3Client' = boto3.client(
"s3",
aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', ''),
aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', ''),
region_name=os.environ.get('AWS_REGION', 'us-east-1')
)
print("Listing S3 buckets...")
response: 'ListBucketsOutputTypeDef' = s3_client.list_buckets()
bucket_names = [bucket['Name'] for bucket in response.get('Buckets', [])]
return bucket_names
if __name__ == "__main__":
import os
# Ensure AWS credentials and region are set in environment variables for a runnable example
# e.g., export AWS_ACCESS_KEY_ID='YOUR_KEY' AWS_SECRET_ACCESS_KEY='YOUR_SECRET' AWS_REGION='us-east-1'
if not all(os.environ.get(k) for k in ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_REGION']):
print("Please set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION environment variables.")
else:
try:
buckets = list_s3_bucket_names()
if buckets:
print(f"Found buckets: {', '.join(buckets)}")
else:
print("No S3 buckets found.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingPython 3.8 support has been removed in `mypy-boto3-builder` version 8.12.0, which generates this package. Projects using `types-boto3-s3` must now target Python 3.9 or newer.fixUpgrade your Python environment to 3.9 or higher.
affects: >=8.12.0 (builder), >=1.42.85 (types-boto3-s3)
breakingThe `mypy-boto3-builder` (version 8.9.0) introduced changes to `TypeDef` naming conventions for service operations, specifically shortening packed argument names (e.g., `CreateDistributionRequestRequestTypeDef` -> `CreateDistributionRequestTypeDef`) and moving `Extra` postfixes. This might require updating type hint declarations for specific S3 operations if your code relies on these specific `TypeDef` names.fixReview and update `TypeDef` import paths and names in your code to match the new conventions.
affects: >=8.9.0 (builder)
gotchaThis package (`types-boto3-s3`) provides *only* type annotations. The actual `boto3` library must be installed separately for your code to run correctly. This package is a development dependency, not a runtime dependency.fixEnsure `boto3` is installed in your runtime environment (e.g., `pip install boto3`).
affects: all
gotchaFor optimal performance and to avoid unnecessary runtime dependencies, always enclose `types-boto3-s3` imports within an `if TYPE_CHECKING:` block. This ensures that the type stubs are only processed by static analysis tools and not imported at runtime.fixWrap type stub imports like `from types_boto3_s3.client import S3Client` with `if TYPE_CHECKING: ...`.
affects: all
gotchaPyCharm users may experience slow performance or high CPU usage due to how PyCharm handles `Literal` overloads with `types-boto3` packages. In such cases, using `types-boto3-lite` (e.g., `pip install types-boto3-lite[s3]`) is recommended, which offers a more RAM-friendly alternative by not providing `session.client`/`resource` overloads, requiring explicit type annotations.fixConsider `pip uninstall types-boto3-s3` and `pip install types-boto3-lite[s3]` if experiencing PyCharm performance issues.
affects: all
Upgrade
Version history
1.43.66latest on PyPI · released Aug 7, 2026
Audit
Dependencies
boto3requiredProvides the runtime functionality that types-boto3-s3 offers type hints for. This package is only stubs.
mypyoptionalA common static type checker used to leverage these type annotations.
typing-extensionsoptionalMay be required for full type compatibility on older Python versions, though modern versions often use built-in typing features. The builder dynamically determines this dependency.