Botocore Stubs provides comprehensive type annotations and code completion for the `botocore` library, the low-level interface to Amazon Web Services. This package, part of the `mypy_boto3_builder` project, is designed to enhance static type analysis with tools like MyPy and Pyright, and improve IDE auto-completion for `botocore`'s dynamically generated classes. It is actively maintained with versions aligned to corresponding `botocore` releases, with the current version being 1.42.41.
Install & Compatibility
Where this runs
tested against v1.43.14 · 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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
S3Client
✓ from botocore_stubs.client import S3Client
✗ from botocore_stubs.client import S3Client
This quickstart demonstrates how to initialize a botocore session and create an S3 client. With `botocore-stubs` installed, type checkers like MyPy or Pyright will provide full code completion and static analysis for the `s3_client` object and its methods, such as `list_buckets()`.
import os
from botocore.session import Session
from botocore.client import S3Client # For type hinting the client
def get_s3_client() -> S3Client:
"""
Returns a typed S3 client from botocore.
botocore-stubs provides the type hints for S3Client.
"""
# Ensure AWS credentials are set up, e.g., via environment variables
# AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
session = Session()
# The return type of session.create_client('s3') is dynamically generated.
# The type checker uses botocore-stubs to infer it as S3Client.
return session.create_client('s3', region_name=os.environ.get('AWS_REGION', 'us-east-1'))
if __name__ == "__main__":
s3_client = get_s3_client()
try:
# This call will have type hints thanks to botocore-stubs
response = s3_client.list_buckets()
print("Successfully listed S3 buckets:")
for bucket in response.get('Buckets', []):
print(f"- {bucket['Name']}")
except Exception as e:
print(f"Error listing S3 buckets: {e}")
print("Ensure you have AWS credentials configured (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION environment variables).")
Debug
Known issues
gotchabotocore-stubs only provides type hints for the low-level `botocore` library, not for the higher-level `boto3` library. Boto3 includes additional abstractions (e.g., `resource` objects, specific helper methods like `upload_file`) that `botocore-stubs` will not type. For `boto3` specific typing, consider `boto3-stubs` (part of the same `mypy_boto3_builder` project).fixIf using `boto3`, install `boto3-stubs` (e.g., `pip install boto3-stubs[essential]`) in addition to or instead of `botocore-stubs`.
affects: All versions
gotchaType stubs are only effective when used with a compatible static type checker (e.g., MyPy, Pyright) or an IDE with strong type-hinting support. Installing `botocore-stubs` alone will not provide runtime changes or visual hints without these tools.fixIntegrate a type checker like MyPy (`pip install mypy`) or Pyright (`npm install -g pyright`) into your development workflow. Configure your IDE (e.g., VSCode with Pylance, PyCharm) to use these tools.
affects: All versions
gotchaThe version of `botocore-stubs` should ideally align with the version of your installed `botocore` library. Mismatched versions may lead to incomplete or incorrect type hints, especially for new features or deprecated APIs in `botocore`.fixEnsure `botocore-stubs` is updated alongside `botocore`. Use `pip install --upgrade botocore-stubs botocore` to keep them synchronized, or specify exact versions in your `requirements.txt`.
affects: All versions
breakingVersion 1.29.0 removed deprecated stubs for client and endpoint_provider modules. If you were relying on type hints for previously deprecated interfaces within these modules, your type checking might now fail or report missing attributes.fixUpdate your code to use the non-deprecated `botocore` APIs. Consult the `botocore` documentation and `botocore-stubs` changelog for details on specific removed stubs.
affects: 1.29.0 and later
breakingVersion 1.29.26 included a fix for `RuleSetStandardLibrary` naming within the `endpoint_provider` module. If your code directly referenced this internal naming for type hints before this fix, it might now cause type checker errors due to the correction.fixReview any direct type references to `botocore.endpoint_provider.RuleSetStandardLibrary` or related components and adjust to the corrected naming, if applicable. Direct interaction with these internal components is generally discouraged.
affects: 1.29.26 and later
breakingThe `botocore` library itself is not installed. This module is a core dependency and must be present for any `botocore` (or `boto3`) related code to run.fixInstall `botocore` using pip (e.g., `pip install botocore`). Ensure it's listed in your project's dependencies (e.g., `requirements.txt`).
affects: All versions
breakingThe `botocore` library must be installed for your application to run. `botocore-stubs` provides only type hints, not the runtime library itself.fixEnsure `botocore` is installed in your environment (e.g., `pip install botocore`). If you are using `boto3`, `botocore` is typically installed as a dependency, but direct usage requires explicit installation.
affects: All versions
Audit
Dependencies
botocorerequiredProvides the runtime implementation that botocore-stubs annotates. The stub package is useless without botocore itself.
types-awscrtoptionalRequired for type annotations related to the AWS Common Runtime (awscrt) components used by botocore.