pydantic-settings-aws 1.2.0b1

Load Pydantic v2 settings from AWS Secrets Manager and SSM Parameter Store

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

✨ 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:

{
    "username": "admin",
    "password": "s3cr3t"
}

Then create your settings class:

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
• Typed field descriptors Secrets and SSM as ergonomic alternatives to raw dict metadata
• Structured exception hierarchy (SecretNotFoundError, ParameterNotFoundError, etc.) for precise error handling
• 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

pip install pydantic-settings-aws

Or with uv:

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.

🔐 Secrets Manager — with boto3 client

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:

{
    "username": "admin",
    "password": "admin",
    "name": "John"
}

📦 SSM Parameter Store

from typing import Annotated
from pydantic_settings_aws import AWSSettingsConfigDict, ParameterStoreBaseSettings, SSM


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 SSM descriptor
    db_port: Annotated[str, SSM(name="/myapp/prod/db/port")]

🙋🏾‍♂️ Secrets Manager — with AWS profile

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

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)

aws sso login --profile my-profile

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.