boto3-refresh-session is a simple Python package with a drop-in replacement for boto3.Session named RefreshableSession. It automatically refreshes temporary AWS credentials, caches clients, and supports MFA token providers. It supports automatic temporary AWS security credential refresh for STS, IOT Core, and custom credential callables. And it is thoroughly tested, regularly updated, comprehensively documentated, and published to PyPI.
Although boto3 already supports automatic temporary credential refresh via role assumption as configured in ~/.aws/config, there are
scenarios and edge cases where that is insufficient. Below are just a few examples:
- Profiles or configs are unavailable or impractical (e.g., containerized or serverless environments)
- You need to explicitly assume roles in a program (not profiles or configs) and hand those credentials around without worrying about expiration
- Custom credential providers are required (e.g. IOT, external ID, etc.)
boto3-refresh-session exists to fill those gaps (and others not listed) while maintaining full compatibility with boto3.
Although there are other open source tools available which address automatic temporary AWS credential refresh, boto3-refresh-session is ergonomically designed to feel like an extension of boto3 (with a few extra parameters) rather than a separate library with a completely unfamiliar API. Using boto3-refresh-session, you can initialize service clients, resources, collections, etc. from RefreshableSession exactly like you would in boto3. More, the available alternatives to boto3-refresh-session do not support the breadth of features that boto3-refresh-session does, such as client caching, MFA token provider support, or IoT Core X.509 credential refresh, among others. Even if you don't need boto3-refresh-session's core feature (automatic temporary AWS credential refresh), the client caching feature may still be useful to you.
Recognized during AWS Community Day Midwest on June 5th, 2025 (my birthday!).
A testimonial from an engineer at Netflix:
Most of my work is on tooling related to AWS security, so I'm pretty choosy about boto3 credentials-adjacent code. I often opt to just write this sort of thing myself so I at least know that I can reason about it. But I found boto3-refresh-session to be very clean and intuitive [...] We're using AWS Lambda to perform lots of operations across several regions in hundreds of accounts, over and over again, all day every day. And it turns out that there's a surprising amount of overhead to creating boto3 clients (mostly deserializing service definition json), so we can run MUCH more efficiently if we keep a cache of clients, all equipped with automatically refreshing sessions.
boto3-refresh-session is available on PyPI.
# with pip
pip install boto3-refresh-session
# with pip + iot as an extra
pip install boto3-refresh-session[iot]
# installation for contributors
pip install boto3-refresh-session[iot,dev]Refer to the official usage documentation for detailed guidance on how to use boto3-refresh-session.
Refer to the official API documentation for technical information about boto3-refresh-session.
Refer to the changelog for additional information on specific versions and releases.
Beginning v7.0.0, boto3-refresh-session is licensed under Mozilla Public License 2.0 (MPL-2.0). Earlier versions remain licensed under the MIT License.
Refer to the contributing guidelines for additional information on contributing to boto3-refresh-session.
The people listed below inspired features, adopted boto3-refresh-session early, provided critical feedback, and more. Thank you for all of your support, encouragement, and guidance which make this project possible.
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}
