{"id":660,"library":"mypy-boto3-s3","title":"mypy-boto3-s3 Type Annotations for AWS S3","description":"mypy-boto3-s3 provides comprehensive type annotations for the `boto3` AWS S3 service, enhancing type checking, code completion, and error detection in Python projects. It is generated by `mypy-boto3-builder`, ensuring compatibility with popular IDEs (VSCode, PyCharm) and type checkers (mypy, pyright). The library version typically mirrors the corresponding `boto3` version, indicating active and frequent releases in sync with AWS SDK updates.","status":"active","version":"1.42.67","language":"python","source_language":"en","source_url":"https://github.com/youtype/mypy_boto3_builder","tags":["boto3","aws","s3","type-annotations","mypy","stubs","python"],"install":[{"cmd":"pip install mypy-boto3-s3 boto3","lang":"bash","label":"Install standalone S3 stubs and boto3"},{"cmd":"pip install 'boto3-stubs[s3]' boto3","lang":"bash","label":"Install S3 stubs as part of boto3-stubs (recommended)"}],"dependencies":[{"reason":"This package provides type annotations for the boto3 library, so boto3 is required for runtime functionality.","package":"boto3","optional":false},{"reason":"Required for older Python versions to support newer typing features. Automatically managed by install_requires.","package":"typing-extensions","optional":true}],"imports":[{"note":"The correct type annotation for a boto3 S3 client is provided by `mypy-boto3-s3`.","wrong":"from boto3.s3.client import S3Client","symbol":"S3Client","correct":"from mypy_boto3_s3.client import S3Client"},{"note":"The correct type annotation for a boto3 S3 service resource is provided by `mypy-boto3-s3`.","wrong":"from boto3.s3.service_resource import S3ServiceResource","symbol":"S3ServiceResource","correct":"from mypy_boto3_s3.service_resource import S3ServiceResource"}],"quickstart":{"code":"import boto3\nfrom mypy_boto3_s3.client import S3Client\nfrom mypy_boto3_s3.service_resource import S3ServiceResource, Bucket\n\ndef get_s3_client() -> S3Client:\n    \"\"\"Returns a type-hinted S3 client.\"\"\"\n    # Type is automatically discovered by mypy and IDEs (if configured)\n    return boto3.client(\"s3\")\n\ndef get_s3_resource() -> S3ServiceResource:\n    \"\"\"Returns a type-hinted S3 service resource.\"\"\"\n    # Type is automatically discovered by mypy and IDEs (if configured)\n    return boto3.resource(\"s3\")\n\ndef get_s3_bucket(bucket_name: str) -> Bucket:\n    \"\"\"Returns a type-hinted S3 Bucket resource.\"\"\"\n    s3_resource: S3ServiceResource = boto3.resource(\"s3\")\n    return s3_resource.Bucket(bucket_name)\n\nif __name__ == \"__main__\":\n    s3_client = get_s3_client()\n    print(f\"S3 Client type: {type(s3_client)}\")\n    # Example usage: list buckets\n    try:\n        response = s3_client.list_buckets()\n        print(\"Buckets:\")\n        for bucket in response.get(\"Buckets\", []):\n            print(f\"  - {bucket['Name']}\")\n    except Exception as e:\n        print(f\"Error listing buckets: {e}\")\n\n    # Example resource usage\n    # s3_resource = get_s3_resource()\n    # my_bucket = get_s3_bucket(\"your-bucket-name\")\n    # print(f\"Bucket name: {my_bucket.name}\")\n","lang":"python","description":"This quickstart demonstrates how to obtain type-hinted S3 clients and service resources using `mypy-boto3-s3`. Explicit type annotations for `boto3.client('s3')` and `boto3.resource('s3')` are provided by importing `S3Client` and `S3ServiceResource`. This enables full code completion and type checking for S3 operations."},"warnings":[{"fix":"Upgrade to Python 3.9 or newer, or pin `mypy-boto3-s3` to a version compatible with Python 3.8 (e.g., <1.40.0, corresponding to builder <8.12.0).","message":"Support for Python 3.8 was removed from `mypy-boto3-builder` version 8.12.0 onwards. This affects all generated stub packages, including `mypy-boto3-s3`. Projects on Python 3.8 will need to use an older version of the stubs or upgrade their Python interpreter.","severity":"breaking","affected_versions":"mypy-boto3-builder >= 8.12.0"},{"fix":"Update `TypeDef` import paths and names in your code to reflect the new conventions. Consult the specific service's documentation for the correct new names.","message":"Type Definition (`TypeDef`) naming conventions changed in `mypy-boto3-builder` version 8.9.0. This can lead to shorter names for packed method arguments (e.g., `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`) and reordering of postfixes for conflicting names. Existing explicit imports of these `TypeDef`s will break.","severity":"breaking","affected_versions":"mypy-boto3-builder >= 8.9.0"},{"fix":"For new projects, prefer `types-boto3` and its service-specific extras (`boto3-stubs[s3]`). For existing projects, ensure your stub installation aligns with the `types-boto3` recommendations.","message":"The original `mypy-boto3` package is considered legacy and users are encouraged to migrate to the `types-boto3` ecosystem. While `mypy-boto3-s3` is a specific service stub package, the overarching `mypy-boto3` project has transitioned to `types-boto3`.","severity":"deprecated","affected_versions":"< 8.9.0 (for `mypy-boto3` itself)"},{"fix":"Consider using `boto3-stubs-lite[s3]` for a more RAM-friendly option (requires explicit type annotations), or disable PyCharm's internal type checker and use an external tool like mypy or pyright instead.","message":"PyCharm users might experience slow performance and high CPU usage due to `Literal` overloads. This is a known issue (PY-40997) with PyCharm's type checker.","severity":"gotcha","affected_versions":"All versions with PyCharm"},{"fix":"Ensure `pip install mypy-boto3-s3` (or `boto3-stubs[s3]`) is run in the same virtual environment as your project and type checker. Mypy's `--no-site-packages` flag will disable this functionality if used.","message":"As of `mypy-boto3-builder` 8.12.0, packages migrated to PEP 561 for distributing type information. While this generally improves automatic discovery, it is crucial that the stub package (`mypy-boto3-s3` or `boto3-stubs[s3]`) is installed in the same Python environment where `mypy` or other type checkers are run.","severity":"gotcha","affected_versions":"mypy-boto3-builder >= 8.12.0"},{"fix":"Ensure AWS credentials are properly configured in your environment. Refer to the AWS SDK documentation for Python for guidance on credential configuration.","message":"Interacting with AWS services (e.g., listing S3 buckets) requires valid AWS credentials to be configured in the environment (e.g., via AWS environment variables, shared credential files, or IAM roles). Without credentials, `boto3` operations will fail with an `Unable to locate credentials` error.","severity":"gotcha","affected_versions":"All versions of `boto3` and `mypy-boto3-*` when interacting with AWS"},{"fix":"Ensure AWS credentials are configured correctly in your environment. This can be achieved through environment variables (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`), shared credential files (`~/.aws/credentials`), IAM roles (for EC2 instances or other AWS services), or AWS Single Sign-On (SSO). Refer to the official `boto3` documentation for detailed credential configuration methods.","message":"The application failed to locate AWS credentials, which are required for authenticating with AWS services like S3. This is a common runtime configuration issue with `boto3` itself, independent of `mypy-boto3-s3` type stubs.","severity":"gotcha","affected_versions":"All versions of `boto3` (and consequently any related stub packages like `mypy-boto3-s3`)"}],"env_vars":null,"last_verified":"2026-05-12T17:31:39.758Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `python -m pip install mypy-boto3-s3` or `python -m pip install 'boto3-stubs[s3]'` if you prefer the meta-package approach.","cause":"The `mypy-boto3-s3` package or `boto3-stubs[s3]` was not installed in your Python environment or is not accessible to your interpreter.","error":"ModuleNotFoundError: No module named 'mypy_boto3_s3'"},{"fix":"Ensure `mypy-boto3-s3` (or `boto3-stubs[s3]`) is installed in your environment (`python -m pip install mypy-boto3-s3`) and that mypy is run within the correct virtual environment. You might also need to explicitly configure mypy to follow imports or ensure your IDE uses the correct interpreter.","cause":"Mypy cannot find the type definitions for the `boto3` library, likely because `mypy-boto3-s3` or `boto3-stubs` is not installed, or your `mypy` configuration is incorrect (e.g., virtual environment not activated).","error":"mypy: Cannot find implementation or library stub for module 'boto3'"},{"fix":"Explicitly import and use the appropriate `TypeDef` for the boto3 response from `mypy_boto3_s3.type_defs`. For example, `response: ListBucketsOutputTypeDef = s3_client.list_buckets()` will provide precise type checking for the dictionary structure.","cause":"This runtime error occurs when you attempt to access an attribute on a dictionary (a boto3 response) as if it were an object, indicating that static type checking failed to catch the issue because the response type was not correctly hinted or defaulted to `Any`.","error":"AttributeError: 'dict' object has no attribute '...' (when accessing boto3 response attributes)"},{"fix":"Encapsulate type imports within `if TYPE_CHECKING:` blocks to ensure they are only processed by static type checkers and are ignored at runtime. \n```python\nfrom typing import TYPE_CHECKING\n\nif TYPE_CHECKING:\n    from mypy_boto3_s3.client import S3Client\n\ndef my_function(s3_client: S3Client):\n    pass\n```","cause":"Importing stub-only types directly at runtime without wrapping them in an `if TYPE_CHECKING:` block makes `mypy-boto3-s3` a runtime dependency, which can lead to `ModuleNotFoundError` in environments where stubs are not installed, or unnecessary overhead.","error":"from mypy_boto3_s3.client import S3Client (used without if TYPE_CHECKING)"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"1.43.5","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"s3","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.94,"mem_mb":18.6,"disk_size":"53.7M"},{"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":0.9,"mem_mb":18.6,"disk_size":"52.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"s3","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.89,"mem_mb":18.5,"disk_size":"53.5M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.89,"mem_mb":18.5,"disk_size":"51.8M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"s3","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":10.5,"import_time_s":0.67,"mem_mb":18.6,"disk_size":"54M"},{"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":4.5,"import_time_s":0.68,"mem_mb":18.6,"disk_size":"53M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"s3","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.66,"mem_mb":18.5,"disk_size":"54M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.66,"mem_mb":18.5,"disk_size":"52M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"s3","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.24,"mem_mb":20.8,"disk_size":"56.8M"},{"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":1.31,"mem_mb":20.8,"disk_size":"55.1M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"s3","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.42,"mem_mb":20.7,"disk_size":"56.6M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.47,"mem_mb":20.7,"disk_size":"54.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"s3","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.1,"import_time_s":1.17,"mem_mb":20.8,"disk_size":"57M"},{"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":3.9,"import_time_s":1.12,"mem_mb":20.8,"disk_size":"56M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"s3","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.06,"mem_mb":20.7,"disk_size":"57M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.09,"mem_mb":20.7,"disk_size":"55M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"s3","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.03,"mem_mb":19.2,"disk_size":"48.0M"},{"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":1.02,"mem_mb":19.2,"disk_size":"46.3M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"s3","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.11,"mem_mb":19.1,"disk_size":"47.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.09,"mem_mb":19.1,"disk_size":"46.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"s3","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.4,"import_time_s":1.04,"mem_mb":20,"disk_size":"49M"},{"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":3.4,"import_time_s":1.17,"mem_mb":20,"disk_size":"47M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"s3","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.15,"mem_mb":19.1,"disk_size":"48M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.08,"mem_mb":19.1,"disk_size":"47M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"s3","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.11,"mem_mb":20.6,"disk_size":"47.7M"},{"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":1.1,"mem_mb":20.6,"disk_size":"46.1M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"s3","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.09,"mem_mb":20.5,"disk_size":"47.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.06,"mem_mb":20.5,"disk_size":"45.7M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"s3","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.1,"import_time_s":0.98,"mem_mb":20.6,"disk_size":"48M"},{"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":3.1,"import_time_s":1.01,"mem_mb":20.6,"disk_size":"47M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"s3","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.07,"mem_mb":20.5,"disk_size":"48M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.1,"mem_mb":20.5,"disk_size":"46M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"s3","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.76,"mem_mb":17.6,"disk_size":"53.1M"},{"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":0.78,"mem_mb":17.6,"disk_size":"51.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"s3","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":17.5,"disk_size":"53.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.79,"mem_mb":17.5,"disk_size":"51.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"s3","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":12,"import_time_s":0.68,"mem_mb":17.6,"disk_size":"54M"},{"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":4.8,"import_time_s":0.69,"mem_mb":17.6,"disk_size":"52M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"s3","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.67,"mem_mb":17.5,"disk_size":"54M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.69,"mem_mb":17.5,"disk_size":"52M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}