{"id":617,"library":"botocore-stubs","title":"Botocore Stubs","description":"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.","status":"active","version":"1.42.41","language":"python","source_language":"en","source_url":"https://github.com/youtype/botocore-stubs","tags":["type-hinting","stubs","botocore","aws","mypy","pyright","typing"],"install":[{"cmd":"pip install botocore-stubs","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides the runtime implementation that botocore-stubs annotates. The stub package is useless without botocore itself.","package":"botocore","optional":false},{"reason":"Required for type annotations related to the AWS Common Runtime (awscrt) components used by botocore.","package":"types-awscrt","optional":true}],"imports":[{"note":"botocore-stubs integrates directly with botocore; type checkers automatically use the stubs for standard botocore imports. Explicitly importing types for annotation (e.g., in a function signature) uses the original botocore module path.","symbol":"S3Client","correct":"from botocore.client import S3Client"},{"note":"Standard botocore session import, which then uses the stubs for client creation methods.","symbol":"Session","correct":"from botocore.session import Session"}],"quickstart":{"code":"import os\nfrom botocore.session import Session\nfrom botocore.client import S3Client # For type hinting the client\n\ndef get_s3_client() -> S3Client:\n    \"\"\"\n    Returns a typed S3 client from botocore. \n    botocore-stubs provides the type hints for S3Client.\n    \"\"\"\n    # Ensure AWS credentials are set up, e.g., via environment variables\n    # AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION\n    session = Session()\n    # The return type of session.create_client('s3') is dynamically generated.\n    # The type checker uses botocore-stubs to infer it as S3Client.\n    return session.create_client('s3', region_name=os.environ.get('AWS_REGION', 'us-east-1'))\n\nif __name__ == \"__main__\":\n    s3_client = get_s3_client()\n    try:\n        # This call will have type hints thanks to botocore-stubs\n        response = s3_client.list_buckets()\n        print(\"Successfully listed S3 buckets:\")\n        for bucket in response.get('Buckets', []):\n            print(f\"- {bucket['Name']}\")\n    except Exception as e:\n        print(f\"Error listing S3 buckets: {e}\")\n        print(\"Ensure you have AWS credentials configured (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION environment variables).\")\n","lang":"python","description":"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()`."},"warnings":[{"fix":"If using `boto3`, install `boto3-stubs` (e.g., `pip install boto3-stubs[essential]`) in addition to or instead of `botocore-stubs`.","message":"botocore-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).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Integrate 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.","message":"Type 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `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`.","message":"The 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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update your code to use the non-deprecated `botocore` APIs. Consult the `botocore` documentation and `botocore-stubs` changelog for details on specific removed stubs.","message":"Version 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.","severity":"breaking","affected_versions":"1.29.0 and later"},{"fix":"Review 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.","message":"Version 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.","severity":"breaking","affected_versions":"1.29.26 and later"},{"fix":"Install `botocore` using pip (e.g., `pip install botocore`). Ensure it's listed in your project's dependencies (e.g., `requirements.txt`).","message":"The `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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure `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.","message":"The `botocore` library must be installed for your application to run. `botocore-stubs` provides only type hints, not the runtime library itself.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T16:45:59.066Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure `botocore-stubs` is installed in the same Python environment your type checker is inspecting. Verify the installation with `pip show botocore-stubs` and run your type checker in the activated environment.","cause":"Your static type checker (like MyPy or Pyright) is not correctly detecting the installed `botocore-stubs` package, often due to an incomplete installation or an incorrect environment setup.","error":"error: Skipping analyzing 'botocore': found module but no type hints or library stubs"},{"fix":"Instead of importing from `botocore.client`, import the specific client type from the corresponding service stub package generated by `mypy_boto3_builder`, typically named `mypy_boto3_<service_name>.client`. For example, for EC2: `from mypy_boto3_ec2.client import EC2Client`.","cause":"This occurs when attempting to import specific AWS service client types (e.g., `EC2Client`, `S3Client`) directly from `botocore.client`, which does not expose these dynamically generated types for static analysis.","error":"AttributeError: module 'botocore.client' has no attribute 'EC2'"},{"fix":"For PyCharm, it is often recommended to use `boto3-stubs-lite` for only the specific services you use (e.g., `pip install boto3-stubs-lite[s3,ec2]`) or to disable PyCharm's internal type checker and rely on external tools like MyPy or Pyright.","cause":"The comprehensive `boto3-stubs` package (which includes `botocore-stubs`) generates a large number of `Literal` overloads for `boto3.client` and `boto3.resource` calls, which can significantly degrade performance in IDEs like PyCharm due to intensive type inference.","error":"Typing/Reformatting/Autocomplete lags when stubs for boto3 are installed"},{"fix":"Import and use the precise `TypeDef` classes provided by the `mypy_boto3_*` stub packages to correctly type your AWS request parameters or response handling. For example: `from mypy_boto3_health.type_defs import DateTimeRangeTypeDef`.","cause":"You are providing a generic Python dictionary where a specific `TypedDict` structure, generated by `mypy_boto3_builder` for AWS service responses or parameters, is expected by the type checker.","error":"error: Argument \"X\" to \"Y\" has incompatible type \"dict[str, Any]\"; expected \"DateTimeRangeTypeDef\""}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"1.42.41","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"18.4M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":null,"mem_mb":null,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"20.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":null,"mem_mb":null,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"12.1M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":null,"mem_mb":null,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"11.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":null,"mem_mb":null,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"17.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.2,"import_time_s":null,"mem_mb":null,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}