pydantic-settings-export

Generate documentation and example config files from pydantic-settings models.

pydantic-settings-export reads BaseSettings classes or instances and writes the same configuration contract to the files your project already uses: Markdown documentation, .env.example, TOML examples, or plain text output.

What It Exports

The exporter understands:

• Field(description=...), Field(examples=...), aliases, deprecation markers, defaults, and required fields.
• env_prefix, env_nested_delimiter, case_sensitive, nested settings models, and populate_by_name.
• settings classes, settings instances, or a whole module containing BaseSettings subclasses.
• generator-specific settings and extend_settings overrides when different outputs need different settings models.

Requirements

• Python 3.10+
• pydantic >= 2.7
• pydantic-settings >= 2.3

Optional extras:

Installation

pip install pydantic-settings-export
pip install "pydantic-settings-export[toml]"
pip install "pydantic-settings-export[email,regions,toml]"

For CLI-only usage:

pipx install pydantic-settings-export
uv tool install pydantic-settings-export

Quick Start

Create a settings model:

from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict


class AppSettings(BaseSettings):
    """Application configuration."""

    model_config = SettingsConfigDict(env_prefix="APP_")

    debug: bool = Field(False, description="Enable debug mode.")
    api_key: str = Field(..., description="API key used by the application.")

Add exporter configuration to pyproject.toml:

[tool.pydantic_settings_export]
project_dir = "."
default_settings = ["app.settings:AppSettings"]

[[tool.pydantic_settings_export.generators.markdown]]
paths = ["docs/configuration.md"]

[[tool.pydantic_settings_export.generators.dotenv]]
paths = [".env.example"]

Run the exporter:

pydantic-settings-export

or pass settings directly:

pydantic-settings-export app.settings:AppSettings
pse app.settings

module:attribute imports one settings class or instance. A plain module path imports all BaseSettings subclasses defined in that module.

CLI

# Use settings from pyproject.toml
pydantic-settings-export

# Export one class
pydantic-settings-export app.settings:AppSettings

# Auto-discover BaseSettings subclasses in a module
pydantic-settings-export app.settings

# Load values needed while importing settings
pydantic-settings-export --env-file .env -- app.settings:AppSettings

# Override virtual environment detection
pydantic-settings-export --venv uv app.settings:AppSettings
pydantic-settings-export --venv .venv app.settings:AppSettings
pydantic-settings-export --venv "" app.settings:AppSettings

# Inspect selected generator configuration fields
pydantic-settings-export --generator markdown dotenv -- --help-generators

# Inspect all generator configuration fields
pydantic-settings-export --help-generators

CLI options override environment variables and pyproject.toml.

Configuration

Global configuration lives under [tool.pydantic_settings_export]:

[tool.pydantic_settings_export]
project_dir = "."
root_dir = "."
default_settings = ["app.settings:AppSettings"]
env_file = ".env"
venv = "auto"
respect_exclude = true

[tool.pydantic_settings_export.relative_to]
replace_abs_paths = true
alias = "<project_dir>"

Generator Blocks

Every generator block supports these common fields:

Markdown

[[tool.pydantic_settings_export.generators.markdown]]
paths = ["docs/configuration.md"]
file_prefix = "# Configuration"
table_only = false
to_upper_case = true

[[tool.pydantic_settings_export.generators.markdown]]
paths = ["README.md"]
region = "settings"
table_only = true

Useful options:

dotenv

[[tool.pydantic_settings_export.generators.dotenv]]
paths = [".env.example"]
mode = "all"
split_by_group = true
add_examples = true
to_upper_case = true

Useful options:

TOML

Install the TOML extra first:

pip install "pydantic-settings-export[toml]"

[[tool.pydantic_settings_export.generators.toml]]
paths = ["config.example.toml"]
mode = "all"
comment_defaults = true
section_depth = 2
prefix = "tool.my_app"

Useful options:

pre-commit Hook

The published hook can keep generated files current in another project:

repos:
  - repo: https://github.com/jag-k/pydantic-settings-export
    rev: v1.0.0
    hooks:
      - id: pydantic-settings-export
        files: ^app/settings\.py$
        additional_dependencies:
          - pydantic-settings-export[email,regions,toml]

When the hook needs to import packages from your project, configure venv discovery:

[tool.pydantic_settings_export]
venv = "auto"

Detection order for "auto" is ./venv, ./.venv, uv, then Poetry.

Python API

The API is useful when you need to run exporters from tests, scripts, or a custom workflow.

from pathlib import Path

from pydantic import Field
from pydantic_settings import BaseSettings

from pydantic_settings_export import Exporter, PSESettings
from pydantic_settings_export.generators.dotenv import DotEnvGenerator, DotEnvSettings
from pydantic_settings_export.generators.markdown import MarkdownGenerator, MarkdownSettings


class AppSettings(BaseSettings):
    """Application configuration."""

    debug: bool = Field(False, description="Enable debug mode.")
    api_key: str


settings = PSESettings(project_dir=Path("."), root_dir=Path("."))
generators = [
    MarkdownGenerator(settings, MarkdownSettings(paths=[Path("docs/configuration.md")])),
    DotEnvGenerator(settings, DotEnvSettings(paths=[Path(".env.example")])),
]

updated_files = Exporter(settings, generators).run_all(AppSettings)

You can pass a settings instance instead of a class when the generated output should include runtime values:

app_settings = AppSettings(api_key="secret", debug=True)
Exporter(settings, generators).run_all(app_settings)

Examples

Generated examples in this repository:

• examples/.env.example
• examples/.env.only_optional_mode.example
• examples/Configuration.md
• examples/SimpleConfiguration.md
• examples/InjectedConfiguration.md
• examples/config.example.toml
• examples/pyproject.example.toml

The repository's own export configuration is in pyproject.toml.

Development

This project uses uv, prek, Ruff, and ty.

uv sync --all-extras --dev
uv run pytest
uv run ruff check . --fix
uv run ruff format .
uv run ty check
uv run prek run --all-files

Generated documentation and examples are refreshed with:

uv run pydantic-settings-export

Contributing

Before opening a pull request:

1. Create a GitHub issue first.
2. Fork the repository.
3. Create a branch named <domain>/<issue-number>-<short-description>, where <domain> is fix or feature.
4. Make the change and update generated examples/docs when behavior changes.
5. Open a PR with a short changelog in the description.

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Support

• Issue Tracker
• Discussions
• Wiki

License

MIT