Install & Compatibility
Where this runs
tested against v1.43.81 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 24.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.0s · import 0.000s · 267MB
133MB installed
● package 133MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
EC2Client
✓ from mypy_boto3_ec2 import EC2Client
✗ from mypy_boto3_ec2 import EC2Client
This example demonstrates how to use `mypy-boto3-ec2` to type-hint an EC2 client and process its responses with type-safe accessors. It lists all EC2 instances in the default region.
import boto3
from mypy_boto3_ec2.client import EC2Client
from mypy_boto3_ec2.type_defs import InstanceTypeDef, ReservationTypeDef
def list_ec2_instances() -> None:
# Type-hint the boto3 client for EC2
ec2_client: EC2Client = boto3.client('ec2')
print('Describing EC2 instances...')
response = ec2_client.describe_instances()
# Use type definitions for better type checking on the response
for reservation in response.get('Reservations', []):
reservation_typed: ReservationTypeDef = reservation
for instance in reservation_typed.get('Instances', []):
instance_typed: InstanceTypeDef = instance
instance_id = instance_typed.get('InstanceId', 'N/A')
instance_type = instance_typed.get('InstanceType', 'N/A')
state = instance_typed.get('State', {}).get('Name', 'N/A')
print(f' Instance ID: {instance_id}, Type: {instance_type}, State: {state}')
if __name__ == '__main__':
# This quickstart assumes AWS credentials are configured (e.g., via environment variables or ~/.aws/credentials)
list_ec2_instances()
Debug
Known issues
breakingPython 3.8 support was removed for all `mypy-boto3-*` packages, including `mypy-boto3-ec2`, starting from version `8.12.0` of the builder. Projects on Python 3.8 will need to upgrade their Python version to 3.9+.fixUpgrade your Python environment to 3.9 or higher. For example, `python3.9 -m pip install mypy-boto3-ec2`.
affects: >=8.12.0 (builder version, corresponds to `mypy-boto3-ec2` versions after this point)
gotchaIt's crucial to install `mypy-boto3-ec2` (or any `mypy-boto3-*` package) with a version that matches your `boto3` installation as closely as possible. Mismatched versions can lead to incorrect type hints or `mypy` errors.fixEnsure `pip install boto3==X.Y.Z mypy-boto3-ec2==X.Y.Z` where `X.Y.Z` is the desired boto3 version. The `mypy-boto3-*` packages are versioned to align with `boto3`.
affects: All versions
breakingFrom builder version `8.9.0`, TypeDef names for packed method arguments were shortened (e.g., `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`). Additionally, conflicting TypeDef `Extra` postfixes were moved (e.g., `CreateDistributionExtraRequestTypeDef` became `CreateDistributionRequestExtraTypeDef`).fixReview and update explicit `TypeDef` imports and usage in your code to match the new, potentially shorter or reordered naming conventions. Rely on IDE auto-completion for correct names.
affects: >=8.9.0 (builder version, impacts `mypy-boto3-ec2` versions after this point)
gotchaAWS service names can change or be deprecated (e.g., `sms-voice` was replaced by `pinpoint-sms-voice` for `mypy-boto3-*` packages in builder version `8.11.0`). While `ec2` is stable, be aware that you might need to update the specific `mypy-boto3-*` package if you work with other AWS services whose names evolve.fixAlways check the `mypy-boto3-builder` release notes for changes affecting specific service packages. If a service name changes, you may need to uninstall the old `mypy-boto3-OLDNAME` package and install `mypy-boto3-NEWNAME`.
affects: All versions
breakingBoto3 clients require an AWS region to be specified. If no region is explicitly configured in your environment or code, `botocore.exceptions.NoRegionError` will be raised.fixEnsure an AWS region is configured. This can be done by setting the `AWS_REGION` or `AWS_DEFAULT_REGION` environment variable, configuring your AWS CLI, or passing the `region_name` argument directly to `boto3.client('ec2', region_name='your-aws-region')`. affects: All versions
gotchaWhen using `boto3` clients, including those with `mypy-boto3-*` type hints, it is mandatory to configure an AWS region. This error occurs if no region is specified via environment variables (e.g., `AWS_DEFAULT_REGION`), AWS config files, or directly in the client creation (e.g., `boto3.client('ec2', region_name='us-east-1')`).fixEnsure an AWS region is configured. You can set the `AWS_DEFAULT_REGION` environment variable (e.g., `export AWS_DEFAULT_REGION=us-east-1`) or explicitly pass `region_name` to the `boto3.client()` call (e.g., `ec2_client = boto3.client('ec2', region_name='us-east-1')`). affects: All versions
Upgrade
Version history
1.43.81latest on PyPI · released Aug 26, 2026
Audit
Dependencies
boto3requiredProvides the actual AWS SDK runtime; these stubs are for type-checking it.
mypyrequiredThe static type checker that utilizes these stubs.