{"id":593,"library":"types-s3transfer","title":"Type Annotations for s3transfer","description":"types-s3transfer provides static type annotations and code completion for the `s3transfer` package, an Amazon S3 Transfer Manager. It significantly enhances IDE support and enables robust static type checking for Python applications that utilize `s3transfer` for efficient file transfers to and from AWS S3. Part of the `mypy_boto3_builder` project, this package is actively maintained, with its version (0.16.0) intended to align with the `s3transfer` version it types.","status":"active","version":"0.16.0","language":"python","source_language":"en","source_url":"https://github.com/youtype/types-s3transfer","tags":["typing","stubs","aws","s3","boto3","type-annotations","mypy","pyright"],"install":[{"cmd":"pip install types-s3transfer","lang":"bash","label":"Install"}],"dependencies":[{"reason":"This package provides type stubs for the 's3transfer' library, which must be installed for runtime functionality. The stub versions are intended to align with the corresponding s3transfer versions.","package":"s3transfer","optional":false}],"imports":[{"wrong":"from s3transfer-stubs import S3Transfer","symbol":"S3Transfer","correct":"from s3transfer_stubs import S3Transfer"}],"quickstart":{"code":"import boto3\nfrom s3transfer.manager import S3Transfer, TransferConfig\nfrom s3transfer.futures import TransferFuture\nimport os\n\ndef upload_file_to_s3(local_filepath: str, bucket_name: str, s3_key: str) -> TransferFuture:\n    # Initialize S3 client\n    s3_client = boto3.client(\n        's3',\n        region_name=os.environ.get('AWS_REGION', 'us-east-1'),\n        aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', 'DUMMY_KEY'),\n        aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', 'DUMMY_SECRET')\n    )\n\n    # Configure transfer (optional)\n    transfer_config = TransferConfig(\n        multipart_threshold=8 * 1024 * 1024, # 8 MB\n        max_concurrency=10\n    )\n\n    # Create S3Transfer manager\n    transfer_manager = S3Transfer(s3_client, transfer_config)\n\n    # Perform upload\n    future: TransferFuture = transfer_manager.upload_file(local_filepath, bucket_name, s3_key)\n    print(f\"Uploading {local_filepath} to s3://{bucket_name}/{s3_key}\")\n    return future\n\nif __name__ == '__main__':\n    # Example usage (replace with actual values for testing)\n    dummy_filepath = 'temp_file.txt'\n    dummy_bucket = 'your-test-bucket'\n    dummy_s3_key = 'test-upload/my_document.txt'\n\n    # Create a dummy file\n    with open(dummy_filepath, 'w') as f:\n        f.write('Hello from types-s3transfer quickstart!')\n\n    print(f\"Created dummy file: {dummy_filepath}\")\n\n    try:\n        # The 'types-s3transfer' package ensures that 'future' is correctly typed as TransferFuture\n        future = upload_file_to_s3(dummy_filepath, dummy_bucket, dummy_s3_key)\n        future.result() # Wait for the upload to complete\n        print(f\"Upload successful: s3://{dummy_bucket}/{dummy_s3_key}\")\n    except Exception as e:\n        print(f\"Upload failed: {e}\")\n    finally:\n        # Clean up the dummy file\n        if os.path.exists(dummy_filepath):\n            os.remove(dummy_filepath)\n            print(f\"Removed dummy file: {dummy_filepath}\")\n\n# To benefit from type hints, ensure 'types-s3transfer' is installed in your environment.\n# Type checkers like MyPy or Pyright will then provide suggestions and error checking.","lang":"python","description":"This quickstart demonstrates how to use the underlying `s3transfer` library for uploading a file to S3. With `types-s3transfer` installed in your environment, your IDE and static type checker (e.g., MyPy, Pyright) will provide accurate type hints for `S3Transfer`, `TransferConfig`, and `TransferFuture` objects, improving development experience and helping catch type-related errors before runtime."},"warnings":[{"fix":"Ensure both `s3transfer` and `types-s3transfer` are installed: `pip install s3transfer types-s3transfer`.","message":"It's crucial to install `s3transfer` alongside `types-s3transfer`. `types-s3transfer` provides only type stubs and does not contain the runtime implementation. Without `s3transfer` installed, your code will fail at runtime with `ModuleNotFoundError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the `types-s3transfer` release notes or `s3transfer` documentation to determine compatible versions. Ideally, keep them in sync, e.g., `pip install 's3transfer==X.Y.Z' 'types-s3transfer==X.Y.Z'`.","message":"Ensure the version of `types-s3transfer` installed closely matches the version of `s3transfer` you are using. Mismatched versions can lead to incorrect type hints or false positive type errors, as the API might have changed between `s3transfer` versions but the stubs don't reflect that change.","severity":"gotcha","affected_versions":"All versions where `s3transfer` and `types-s3transfer` versions diverge."},{"fix":"Upgrade to `types-s3transfer` version `0.6.0.post2` or newer to get the correct `str` return type for `TransferFuture.result()`: `pip install --upgrade types-s3transfer`.","message":"The return type of `TransferFuture.result()` was fixed in `types-s3transfer` version 0.6.0.post2 (and likely corresponding `s3transfer` versions) to correctly return `str`. Older versions of the stubs might have had incorrect `Any` types, potentially masking real type issues or causing confusion.","severity":"breaking","affected_versions":"<=0.6.0.post1"},{"fix":"Ensure a compatible set of `boto3`, `botocore`, and `s3transfer` versions. Often, `pip install boto3` will install compatible `botocore` and `s3transfer` versions. If issues persist, try `pip install 's3transfer==0.4.0'` as a known stable combination with certain `boto3` versions, or refer to `boto3`'s dependency matrix.","message":"Some users have reported `ImportError` for components like `RetriesExceededError` from `s3transfer.exceptions`, often due to version conflicts between `boto3`, `botocore`, and `s3transfer`. While `types-s3transfer` itself is stubs, these underlying runtime issues can affect how correctly the stubs are applied or whether the application even runs.","severity":"gotcha","affected_versions":"s3transfer versions, particularly older ones like `0.4.0` with newer `boto3`/`botocore`."},{"fix":"Install `boto3`: `pip install boto3`.","message":"`boto3` is a required dependency for using `s3transfer` functionality with AWS S3. If `boto3` is not installed, you will encounter a `ModuleNotFoundError` when attempting to import it, preventing any AWS S3 operations.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure `boto3` is installed in your environment: `pip install boto3`.","message":"The package `boto3` is a common dependency when working with AWS services, including those that `s3transfer` interacts with. If `boto3` is not installed, any attempt to import it will result in a `ModuleNotFoundError`.","severity":"breaking","affected_versions":"All versions where `boto3` is required but not installed."}],"env_vars":null,"search_vec":"'0.16.0':65 'activ':60 'align':68 'amazon':20 'annot':2,11,82 'applic':37 'aw':48,77 'boto3':54,79 'builder':55 'check':34 'code':13 'complet':14 'effici':42 'enabl':30 'enhanc':26 'file':43 'ide':27 'intend':66 'maintain':61 'manag':23 'mypi':53,83 'packag':18,58 'part':50 'project':56 'provid':8 'pyright':84 'python':36 'robust':31 's3':21,49,78 's3transfer':4,7,17,40,71 'signific':25 'static':9,32 'stub':76 'support':28 'transfer':22,44 'type':1,6,10,33,74,75,81 'type-annot':80 'types-s3transfer':5 'util':39 'version':64,72","created_at":"2026-03-28T15:20:31.379832+00:00","updated_at":"2026-04-16T23:45:02.703644+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nModuleNotFoundError: No module named 's3transfer_stubs'"},"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"0.16.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/youtype/types-s3transfer","docs":"https://youtype.github.io/mypy_boto3_builder/","changelog":"https://github.com/youtype/types-s3transfer/releases","pypi":"https://pypi.org/project/types-s3transfer/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs","aws"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-08-27","next_check":"2026-07-10","install_tag":"stale"}}