Registry /
type-stubs / mypy-boto3-stepfunctions
Install & Compatibility
Where this runs
tested against v1.43.7 · 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 · 198.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.8s · import 0.000s · 267MB
232MB installed
● package 232MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SFNClient
✓ from mypy_boto3_stepfunctions import SFNClient
✗ from mypy_boto3_stepfunctions import SFNClient
Demonstrates how to obtain a type-hinted Step Functions client and use it to list state machines. The `TYPE_CHECKING` block ensures type hints are available for static analysis without adding runtime dependencies if not desired. The `region_name` is explicitly set using an environment variable for clarity.
import boto3
import os
from typing import TYPE_CHECKING
# These imports are only for type checking purposes.
if TYPE_CHECKING:
from mypy_boto3_stepfunctions.client import SFNClient
from mypy_boto3_stepfunctions.type_defs import ListStateMachinesOutputTypeDef
# boto3 automatically picks up AWS credentials from environment variables
# (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) or ~/.aws/credentials.
# Ensure these are configured for a live AWS connection.
try:
# Get the Step Functions client.
# During static analysis (TYPE_CHECKING is True), 'sfn_client' will be inferred as SFNClient.
# At runtime, it behaves like a standard boto3 client.
sfn_client: "SFNClient" = boto3.client("stepfunctions", region_name=os.environ.get('AWS_REGION', 'us-east-1'))
# Use the typed client. Mypy will validate arguments and the return type.
response: ListStateMachinesOutputTypeDef = sfn_client.list_state_machines(maxResults=10)
print("Successfully listed Step Functions state machines:")
for sm in response["stateMachines"]:
print(f"- {sm['name']} (ARN: {sm['stateMachineArn']})")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure your AWS credentials are configured and you have permissions for Step Functions (states:ListStateMachines).")
Debug
Known issues
breakingSupport for Python 3.8 has been removed across all `mypy-boto3` packages, including `mypy-boto3-stepfunctions`.fixUpgrade your Python environment to version 3.9 or newer.
affects: 8.12.0 and later
breakingTypeDef naming conventions changed in version 8.9.0. Packed method arguments may now use shorter names (e.g., `CreateDistributionRequestRequestTypeDef` -> `CreateDistributionRequestTypeDef`), and conflicting `Extra` postfixes are moved to the end (e.g., `CreateDistributionExtraRequestTypeDef` -> `CreateDistributionRequestExtraTypeDef`).fixReview and update explicit `TypeDef` import names in your codebase if you were referencing them directly. IDEs and type checkers should highlight any breaking changes.
affects: 8.9.0 and later
gotchaPyCharm users may experience slow performance or high CPU usage due to an issue with Literal overloads (PY-40997) when using `boto3-stubs` or individual `mypy-boto3-*` packages.fixConsider using `boto3-stubs-lite` instead of the full package, or disable PyCharm's internal type checker and rely solely on `mypy` or `pyright`.
affects: All versions (due to PyCharm issue)
gotchaWhen conditionally importing `mypy-boto3` types with `if TYPE_CHECKING:` to avoid runtime dependencies, Pylint may report 'undefined variable' errors.fixTo resolve Pylint complaints, you can define dummy `object` types for the imported symbols in the `else` block of your `TYPE_CHECKING` condition, for example: `else: SFNClient = object`.
affects: All versions
Upgrade
Version history
1.43.7latest on PyPI · released May 13, 2026
Audit
Dependencies
boto3requiredProvides the AWS SDK for Python that these type stubs annotate.
mypyoptionalThe primary static type checker for Python, which utilizes these stubs.