A wrapper for executing a command using AWS Assumed Role

aws, profile, assume, role
pip install aws-profile==0.6.1



Wrapper script to generate and pass AWS AssumeRole keys to other scripts


There are two primary ways to use aws-profile, inline using arguments and with environment variables.

Inline Profile Name

aws-profile [-p, --profile <profile name> -r, --region <region>] <command>

Profile Environment Variable

aws-profile --profile dev --region us-west-2 <command> or aws-profile -p dev -r us-west-2 <command>


AWS_CACHE: Set the AWS_CACHE environment variable to control caching. Use AWS_CACHE=false to disable caching, or any other value (or unset) to keep caching enabled. When set to false the MFA code will be requested every time.

Configuring Profiles

aws-profile uses the built in profiles from the AWS CLI. For full details see Named Profiles in the AWS Documentation.

Here is an example of how to configure a profile for a role, with MFA:

[profile my_profile]
role_arn = arn:aws:iam::<account_id>:role/<role_name>
source_profile = default
mfa_serial = arn:aws:iam::<account_id>:mfa/<username>

Where <account_id> is your AWS Account ID, <role_name> is the name of the role you want to assume, and <username> is the username of the AWS User used fo your default profile.


Clone from github (or preferably from your own fork)

git clone

Create a clean virtual environment examples for virtualenv and pyenv with virtualenv wrapper

virtualenv venv source venv/bin/activate


pyenv virtualenv aws-profile pyenv activate aws-profile

Install the development dependencies

pip install -e ".[dev]"

Run the tests before making changes and then again before creating a pull request (There will be 3 warnings about external dependencies which can be ignored)

pytest --cov=awsprofile --cov-report term-missing