{"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":[{"symbol":"S3Transfer","correct":"from s3transfer.manager import S3Transfer"},{"symbol":"TransferConfig","correct":"from s3transfer.manager import TransferConfig"},{"symbol":"TransferFuture","correct":"from s3transfer.futures import TransferFuture"}],"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,"last_verified":"2026-05-12T16:24:02.702Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install the `types-s3transfer` package to provide the necessary type annotations: `pip install types-s3transfer`","cause":"The mypy type checker cannot find type information for the `s3transfer` library because the `types-s3transfer` stub package is not installed or configured correctly.","error":"Missing type stubs for package 's3transfer'"},{"fix":"Import `s3transfer` instead, ensuring both `s3transfer` and `types-s3transfer` are installed for runtime functionality and type checking, respectively: `from s3transfer.manager import TransferManager`","cause":"The `types-s3transfer` package provides only type stubs and is not meant to be imported directly; the actual runtime code resides in the `s3transfer` package.","error":"ModuleNotFoundError: No module named 'types_s3transfer'"},{"fix":"Install the `s3transfer` package. For full type checking support, also install `types-s3transfer`: `pip install s3transfer types-s3transfer`","cause":"The core `s3transfer` library, which contains the actual runtime code, has not been installed.","error":"ModuleNotFoundError: No module named 's3transfer'"},{"fix":"Use `TransferManager` to manage S3 transfers. Ensure `s3transfer` and `types-s3transfer` are installed for correct runtime behavior and static type checking: `from s3transfer.manager import TransferManager`","cause":"The `s3transfer` library's primary interface for transfer operations is `TransferManager`, not `S3Transfer`, or the module structure has changed in newer versions.","error":"AttributeError: module 's3transfer' has no attribute 'S3Transfer'"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"0.16.0","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":"17.9M"},{"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.5,"import_time_s":null,"mem_mb":null,"disk_size":"18M"},{"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":"19.7M"},{"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.6,"import_time_s":null,"mem_mb":null,"disk_size":"20M"},{"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":"11.6M"},{"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.5,"import_time_s":null,"mem_mb":null,"disk_size":"12M"},{"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.3M"},{"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.4,"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.4M"},{"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":1.7,"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-23","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}]}}