{"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,"search_vec":"'activ':65 'annot':6,17,80 'aw':8,21,72,76 'boto3':3,12,20,41,62,75 'builder':42 'check':26 'checker':52 'code':27 'compat':44 'complet':28 'comprehens':15 'correspond':61 'detect':31 'enhanc':24 'ensur':43 'error':30 'frequent':67 'generat':37 'ide':47 'indic':64 'librari':56 'mirror':59 'mypi':2,11,40,53,81 'mypy-boto3-builder':39 'mypy-boto3-s3':1,10 'popular':46 'project':34 'provid':14 'pycharm':49 'pyright':54 'python':33,83 'releas':68 's3':4,9,13,22,77 'sdk':73 'servic':23 'stub':82 'sync':70 'type':5,16,25,51,79 'type-annot':78 'typic':58 'updat':74 'version':57,63 'vscode':48","created_at":"2026-03-28T17:09:18.510083+00:00","updated_at":"2026-04-16T17:11:22.568195+00:00","problems":{"verify_error":"error: Failed to parse: `mypy-boto3-s3 boto3`\n  Caused by: Expected one of `@`, `(`, `<`, `=`, `>`, `~`, `!`, `;`, found `b`\nmypy-boto3-s3 boto3\n              ^"},"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"1.43.14","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/youtype/mypy_boto3_builder","docs":"https://youtype.github.io/boto3_stubs_docs/mypy_boto3_s3/","changelog":null,"pypi":"https://pypi.org/project/mypy-boto3-s3/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs","aws"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"install_fail","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":"verified"}}