Install & Compatibility
Where this runs
tested against v0.2.1 · 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.760s · 50.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.8s · import 0.686s · 51MB
49MB installed
● package 49MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
assume_role
✓ from boto3_assume import assume_role
✗ from boto3_assume import assume_role_session
`assume_role_session` was deprecated in v0.2.0 and replaced by `assume_role`.
assume_role_aio_session
✓ from aioboto3_assume import assume_role_aio_session
✗ from boto3_assume import assume_role_aio_session
`assume_role_aio_session` was moved to the `aioboto3-assume` package in v0.2.0.
This quickstart demonstrates how to use `boto3-assume.assume_role` to obtain a boto3 session with temporary credentials from an assumed IAM role, and then use that session to interact with an AWS service like S3. Ensure your environment has AWS credentials configured (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, or `AWS_PROFILE`) and replace the placeholder `role_arn`.
import boto3_assume
import boto3
import os
# Replace with your actual role ARN and session name
# For local testing, ensure your AWS credentials are configured (e.g., via ~/.aws/credentials or environment variables)
role_arn = os.environ.get('AWS_ASSUME_ROLE_ARN', 'arn:aws:iam::123456789012:role/MyTestRole')
role_session_name = os.environ.get('AWS_ASSUME_SESSION_NAME', 'Boto3AssumeQuickstartSession')
if not role_arn.startswith('arn:aws:iam::'):
print("Warning: AWS_ASSUME_ROLE_ARN not set or invalid. Using a placeholder ARN. This example will likely fail unless configured correctly.")
try:
# Assume the role and get a boto3 session object
assumed_session = boto3_assume.assume_role(
role_arn=role_arn,
role_session_name=role_session_name
)
# Use the assumed session to create a client (e.g., S3)
s3_client = assumed_session.client('s3')
print(f"Successfully assumed role '{role_arn}' with session name '{role_session_name}'.")
# Example: List S3 buckets using the assumed role
print("Attempting to list S3 buckets...")
buckets_response = s3_client.list_buckets()
bucket_names = [b['Name'] for b in buckets_response.get('Buckets', [])]
print(f"Found {len(bucket_names)} S3 buckets: {bucket_names[:3]}...")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure your AWS credentials are configured and the role ARN is correct and accessible.")
Errors
Common errors & fixes
AttributeError: module 'boto3_assume' has no attribute 'assume_role_session'
You are using version 0.2.0 or newer of boto3-assume, but your code is still calling the deprecated `assume_role_session` function.
fixUpdate your import and function call to `from boto3_assume import assume_role` and use `boto3_assume.assume_role(...)`.
ImportError: cannot import name 'assume_role_aio_session' from 'boto3_assume'
`assume_role_aio_session` was moved to a new package, `aioboto3-assume`, in version 0.2.0.
fixInstall `aioboto3-assume` (`pip install aioboto3-assume`) and change your import to `from aioboto3_assume import assume_role_aio_session`.
SyntaxError: future feature annotations is not defined
Your Python version is too old (e.g., 3.7-3.9) for boto3-assume versions 0.1.3 and above, which dropped support for these Python versions.
fixUpgrade your Python environment to version 3.10 or newer.
Upgrade
Version history
0.2.1latest on PyPI · released Jan 15, 2026
Audit
Dependencies
boto3requiredCore dependency for AWS SDK functionality, used for creating and managing AWS sessions.