Install & Compatibility
Where this runs
tested against v1.43.83 · 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 0.710s · 208.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 9.2s · import 0.692s · 209MB
212MB installed
● package 212MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
boto3
✓ import boto3
boto3-stubs-full provides type hints; at runtime, you import boto3 as usual.
S3Client
✓ from typing import TYPE_CHECKING
if TYPE_CHECKING:
from mypy_boto3_s3.client import S3Client
✗ from botocore.client import BaseClient
For explicit type annotations in type-checking contexts, import specific client types from `mypy_boto3_*` sub-packages. Avoid `BaseClient` as it lacks service-specific details.
This quickstart demonstrates using `boto3-stubs-full` with a standard boto3 S3 client. After installing `boto3-stubs-full`, your IDE and static type checkers like MyPy will automatically provide type hints for `boto3` calls. For explicit type annotations, `mypy_boto3_s3.client.S3Client` is imported conditionally for type-checking only.
from typing import TYPE_CHECKING
import boto3
import os
# Boto3-stubs-full enhances type checking for standard boto3 usage.
# For explicit type annotations, import service clients within a TYPE_CHECKING block.
if TYPE_CHECKING:
from mypy_boto3_s3.client import S3Client
def list_s3_buckets(region: str) -> None:
# Initialize an S3 client. IDEs and type checkers will recognize the type
# even without explicit type hints if boto3-stubs-full is installed.
s3_client: S3Client = boto3.client('s3', region_name=region)
print(f"Listing S3 buckets in {region}:")
try:
response = s3_client.list_buckets()
for bucket in response.get('Buckets', []):
print(f"- {bucket['Name']}")
except Exception as e:
print(f"Error listing buckets: {e}")
if __name__ == "__main__":
aws_region = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')
list_s3_buckets(aws_region)
Debug
Known issues
breakingPython 3.8 support has been removed. Projects using Python 3.8 must either upgrade Python or pin `boto3-stubs-full` to a version prior to 8.12.0.fixUpgrade your Python environment to 3.9 or higher, or explicitly specify an older `boto3-stubs-full` version (e.g., `<8.12.0`).
affects: >=8.12.0
breakingThe `sms-voice` service is no longer supported and has been removed. Use `pinpoint-sms-voice` instead.fixMigrate your code to use the `pinpoint-sms-voice` service client instead of `sms-voice`.
affects: >=8.11.0
breakingBreaking changes were introduced to `TypeDef` naming conventions. For example, `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`, and conflicting `Extra` postfixes were moved (e.g., `CreateDistributionExtraRequestTypeDef` to `CreateDistributionRequestExtraTypeDef`).fixUpdate your code to reflect the new `TypeDef` naming conventions as indicated by your type checker.
affects: >=8.9.0
gotchaMismatched versions between `boto3` and `boto3-stubs-full` can lead to incorrect or missing type hints. The `boto3-stubs` project generally aims to keep pace with `boto3` releases.fixAlways install `boto3-stubs-full` with a version compatible with your `boto3` installation, ideally by matching their major and minor versions (e.g., `pip install 'boto3==1.28.x' 'boto3-stubs-full==1.28.x'`).
affects: All versions
gotchaPyCharm users may experience slow performance or high CPU usage due to `Literal` overloads. It is recommended to use `boto3-stubs-lite` or an external type checker (like MyPy or Pyright) with PyCharm's type checker disabled.fixFor PyCharm, consider `pip install boto3-stubs-lite` or disable PyCharm's built-in type checker and use `mypy` or `pyright` externally.
affects: All versions with PyCharm
gotchaWhen importing specific `mypy_boto3_*` types (e.g., `from mypy_boto3_s3.client import S3Client`), it is best practice to wrap these imports within an `if TYPE_CHECKING:` block. Failing to do so can make the stubs an unnecessary runtime dependency, potentially leading to circular import issues or larger deployment sizes.fixAlways use `from typing import TYPE_CHECKING` and `if TYPE_CHECKING: ...` for explicit type imports to ensure they are only processed by type checkers.
affects: All versions
Upgrade
Version history
1.43.83latest on PyPI · released Aug 29, 2026
Audit
Dependencies
boto3requiredThis package provides type stubs for boto3; boto3 itself must be installed to run your code.
botocore-stubsrequiredCore dependency for boto3 stubs.
types-s3transferrequiredCore dependency for boto3 stubs related to S3 transfer.
typing-extensionsrequiredProvides backported typing features for broader Python version compatibility.