https://github.com/ceb10n/pydantic-settings-aws
Pydantic Settings for AWS
https://github.com/ceb10n/pydantic-settings-aws
aws aws-secrets-manager configuration pydantic pydantic-v2 python settings
Last synced: 3 months ago
JSON representation
Pydantic Settings for AWS
- Host: GitHub
- URL: https://github.com/ceb10n/pydantic-settings-aws
- Owner: ceb10n
- License: mit
- Created: 2024-07-11T11:32:10.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2026-04-03T20:52:06.000Z (3 months ago)
- Last Synced: 2026-04-03T20:56:34.588Z (3 months ago)
- Topics: aws, aws-secrets-manager, configuration, pydantic, pydantic-v2, python, settings
- Language: Python
- Homepage: https://ceb10n.github.io/pydantic-settings-aws/
- Size: 1.04 MB
- Stars: 24
- Watchers: 2
- Forks: 3
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Pydantic Settings AWS
[](https://github.com/ceb10n/pydantic-settings-aws/actions)
[](https://codecov.io/github/ceb10n/pydantic-settings-aws)
[](https://pypi.org/project/pydantic-settings-aws)
[](https://pypi.org/project/pydantic-settings-aws)
[](https://docs.pydantic.dev/latest/contributing/#badges)
[](https://pypi.org/project/pydantic-settings-aws)
[](https://pepy.tech/project/pydantic-settings-aws)
`pydantic-settings-aws` extends Pydantic Settings to load configuration from AWS Secrets Manager and SSM Parameter Store directly into type-safe Pydantic models, eliminating the need for manual boto3 parsing or environment variable mapping.
📖 **[Full documentation](https://ceb10n.github.io/pydantic-settings-aws)**
## ✨ Why pydantic-settings-aws?
- Define your configuration once using Pydantic models
- Load secrets and parameters from AWS without manual boto3 code
- Built-in validation, parsing, and type safety
- Works with any AWS authentication method — profiles, SSO, IAM roles, access keys
- Thread-safe and compatible with free-threaded Python
## ⚡ Quick Start
Add your secret to AWS Secrets Manager as a JSON object:
```json
{
"username": "admin",
"password": "s3cr3t"
}
```
Then create your settings class:
```python
from pydantic_settings_aws import AWSSettingsConfigDict, SecretsManagerBaseSettings
class MySettings(SecretsManagerBaseSettings):
model_config = AWSSettingsConfigDict(
secrets_name="my/secret"
)
username: str
password: str
settings = MySettings()
print(settings.username) # "admin"
```
That’s it, `boto3` will resolve your AWS credentials automatically using its standard configuration chain.
## ✅ Features
- Load settings from **AWS Secrets Manager**, **SSM Parameter Store**, or both simultaneously
- Type-safe configuration with full IDE autocomplete via `AWSSettingsConfigDict`
- Multi-region and multi-account support via per-field boto3 clients
- Thread-safe client cache, compatible with free-threaded Python (3.13t, 3.14t)
- Falls back to environment variables, dotenv, and secret files automatically
## 🔧 Requirements
| Python | Pydantic | boto3 |
| :----- | :------- | :---- |
| 3.10+ | v2 | v1 |
## 💽 Installation
```bash
pip install pydantic-settings-aws
```
Or with [uv](https://docs.astral.sh/uv/):
```bash
uv add pydantic-settings-aws
```
## 📦 Usage
You can provide your own boto3 client or let pydantic-settings-aws create one for you. To learn how boto3 resolves credentials, see [Configuring credentials](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#configuring-credentials).
### 🔐 Secrets Manager — with boto3 client
```python
import boto3
from pydantic_settings_aws import AWSSettingsConfigDict, SecretsManagerBaseSettings
client = boto3.client("secretsmanager")
class MySettings(SecretsManagerBaseSettings):
model_config = AWSSettingsConfigDict(
secrets_name="my/secret",
secrets_client=client
)
username: str
password: str
name: str | None = None
settings = MySettings()
```
Your secret content must be valid JSON with keys matching the field names:
```json
{
"username": "admin",
"password": "admin",
"name": "John"
}
```
### 📦 SSM Parameter Store
```python
from typing import Annotated
from pydantic_settings_aws import AWSSettingsConfigDict, ParameterStoreBaseSettings
class MySettings(ParameterStoreBaseSettings):
model_config = AWSSettingsConfigDict(aws_region="us-east-1")
# pydantic-settings-aws looks for a parameter named "db_host"
db_host: str
# explicit parameter name via Annotated
db_port: Annotated[str, "/myapp/prod/db/port"]
```
### 🙋🏾♂️ Secrets Manager — with AWS profile
```python
from pydantic_settings_aws import AWSSettingsConfigDict, SecretsManagerBaseSettings
class MySettings(SecretsManagerBaseSettings):
model_config = AWSSettingsConfigDict(
secrets_name="my/secret",
aws_region="us-east-1",
aws_profile="dev"
)
username: str
password: str
```
### 🔑 Secrets Manager — with access key
```python
from pydantic_settings_aws import AWSSettingsConfigDict, SecretsManagerBaseSettings
class MySettings(SecretsManagerBaseSettings):
model_config = AWSSettingsConfigDict(
secrets_name="my/secret",
aws_region="us-east-1",
aws_access_key_id="aws_access_key_id",
aws_secret_access_key="aws_secret_access_key",
aws_session_token="aws_session_token"
)
username: str
password: str
```
### 🔒 Secrets Manager — with AWS IAM Identity Center (SSO)
```shell
aws sso login --profile my-profile
```
```python
from pydantic_settings_aws import AWSSettingsConfigDict, SecretsManagerBaseSettings
class MySettings(SecretsManagerBaseSettings):
model_config = AWSSettingsConfigDict(
secrets_name="my/secret"
)
username: str
password: str
```
## 👩🏼⚖️ License
This project is licensed under the terms of the [MIT license.](LICENSE)