{"id":2333,"library":"types-aioboto3","title":"Type annotations for aioboto3","description":"types-aioboto3 provides comprehensive type annotations (stubs) for the aioboto3 library, enabling static type checking for asynchronous AWS client operations with tools like Mypy. It's generated by mypy-boto3-builder and aligns with aioboto3 and AWS service changes. The current version is 15.5.0, with frequent updates.","status":"active","version":"15.5.0","language":"en","source_language":"en","source_url":"https://github.com/youtype/mypy_boto3_builder","tags":["aioboto3","async","aws","types","mypy","type-stubs"],"install":[{"cmd":"pip install types-aioboto3","lang":"bash","label":"Install all service stubs (metapackage)"},{"cmd":"pip install types-aioboto3-s3 types-aioboto3-ec2","lang":"bash","label":"Install specific service stubs (recommended for smaller footprint)"}],"dependencies":[{"reason":"Provides the runtime functionality for which these type stubs are generated. This library only provides types, not the runtime.","package":"aioboto3","optional":false}],"imports":[{"note":"Type hints for clients are imported from service-specific sub-packages, even if the main 'types-aioboto3' metapackage is installed.","wrong":"from types_aioboto3 import S3Client","symbol":"S3Client","correct":"from types_aioboto3_s3.client import S3Client"},{"note":"TypeDefs for AWS responses and request bodies are provided by these stubs, not directly from aioboto3 runtime.","wrong":"from aioboto3.s3.type_defs import BucketTypeDef","symbol":"BucketTypeDef","correct":"from types_aioboto3_s3.type_defs import BucketTypeDef"},{"note":"The aioboto3 session object itself is from the runtime library, not the type stubs. The stubs provide types for what `session.client()` returns.","wrong":"from types_aioboto3.session import Session","symbol":"Session","correct":"import aioboto3"}],"quickstart":{"code":"import aioboto3\nimport asyncio\nfrom types_aioboto3_s3.client import S3Client\nfrom types_aioboto3_s3.type_defs import BucketTypeDef\n\nasync def list_s3_buckets_typed():\n    session = aioboto3.Session()\n    async with session.client(\"s3\") as client:\n        # Type hint the client to enable autocompletion and static checks\n        client: S3Client\n        \n        response = await client.list_buckets()\n        \n        # Type hint the list of buckets for better type safety\n        buckets: list[BucketTypeDef] = response.get(\"Buckets\", [])\n        \n        if not buckets:\n            print(\"No S3 buckets found or access denied.\")\n            return\n\n        print(\"S3 Buckets:\")\n        for bucket in buckets:\n            print(f\"  - {bucket['Name']}\")\n\nasync def main():\n    # aioboto3 uses standard AWS credential chain (e.g., environment variables, \n    # ~/.aws/credentials, IAM roles). No hardcoded keys are needed here.\n    await list_s3_buckets_typed()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())","lang":"python","description":"This quickstart demonstrates how to integrate `types-aioboto3` for static type checking with an `aioboto3` S3 client. It shows how to import and apply `S3Client` and `BucketTypeDef` to enhance code clarity, enable IDE autocompletion, and catch potential errors at development time."},"warnings":[{"fix":"Upgrade your Python environment to version 3.9 or newer. Ensure your `pyproject.toml` or `setup.cfg` reflects `python_requires >=3.9`.","message":"As of mypy-boto3-builder 8.12.0 (which generates types-aioboto3), Python 3.8 is no longer supported for any generated packages. Users on Python 3.8 will encounter issues with newer versions.","severity":"breaking","affected_versions":"mypy-boto3-builder >=8.12.0 (types-aioboto3 versions generated by it)"},{"fix":"Update type annotation references in your code to match the new naming conventions. Refer to the specific service stub documentation for updated TypeDef names.","message":"Service-specific TypeDef names for method arguments and conflicting names were changed in mypy-boto3-builder 8.9.0. For example, `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`, and `CreateDistributionExtraRequestTypeDef` became `CreateDistributionRequestExtraTypeDef`.","severity":"breaking","affected_versions":"mypy-boto3-builder >=8.9.0 (types-aioboto3 versions generated by it)"},{"fix":"Replace references to `sms-voice` with `pinpoint-sms-voice` in your code and update imports and client calls accordingly (e.g., `session.client(\"pinpoint-sms-voice\")` and `from types_aioboto3_pinpoint_sms_voice import PinpointSMSVoiceClient`).","message":"The `sms-voice` service stubs were removed in mypy-boto3-builder 8.11.0. Users should migrate to `pinpoint-sms-voice` for related functionality.","severity":"deprecated","affected_versions":"mypy-boto3-builder >=8.11.0 (types-aioboto3 versions generated by it)"},{"fix":"Ensure `pip install aioboto3` is performed in your environment alongside `types-aioboto3`.","message":"This library provides type stubs for `aioboto3` and does not include the `aioboto3` runtime itself. It's solely for static type checking; you must install `aioboto3` separately for your application to run.","severity":"gotcha","affected_versions":"all"},{"fix":"Always use `from types_aioboto3_SERVICE.client import ServiceClient` and `from types_aioboto3_SERVICE.type_defs import ...` for specific service types.","message":"Even if you install the `types-aioboto3` metapackage (which includes all service stubs), the type hints (e.g., Client classes, TypeDefs) must be imported from their respective service-specific sub-packages (e.g., `types_aioboto3_s3`).","severity":"gotcha","affected_versions":"all"},{"fix":"Periodically update both `aioboto3` and `types-aioboto3` simultaneously, or pin their versions in your `requirements.txt` or `pyproject.toml` to prevent mismatches.","message":"It is recommended to keep the version of `types-aioboto3` (or its service-specific sub-packages) synchronized with your `aioboto3` runtime version to ensure accurate type hints, as stubs are generated for specific `aioboto3` versions and AWS API shapes.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}