Pydantic Config

Pydantic Config extends Pydantic’s BaseSettings to support loading configuration from files like JSON, INI, TOML, and YAML — in addition to environment variables.

---

Table of Contents

• Why Pydantic Config?
• Installation
• Quick Start
• Loading Multiple Config Files
• Supported File Formats
• Using .env Files
• Requiring Config Files to Exist
• Merging
• Handling Duplicates in Merged Lists
• License

---

Why Pydantic Config?

✅ Load settings from .json, .ini, .toml, .yaml, and .env files.
✅ Support for multiple files with override/merge strategies.
✅ Compatible with Pydantic v2 BaseSettings.
✅ Lightweight and simple integration.

---

Installation

Install with pip:

pip install pydantic-config

Or with conda (via the conda-forge channel):

conda install pydantic-config -c conda-forge

Optional Dependencies

To enable additional file formats, you can install optional dependencies:

Format	Install Command
YAML	pip install pydantic-config[yaml]
TOML (for Python < 3.11)	pip install pydantic-config[toml]

To install all optional dependencies:

pip install pydantic-config[all]

---

Quick Start

Load settings from a config file:

config.toml

app_name = "Python Application"
description = "Test application description"

settings.py

from pydantic_config import SettingsModel, SettingsConfig

class Settings(SettingsModel):
    app_id: str = 1
    app_name: str = None
    description: str = None
    log_level: str = 'INFO'
    
    model_config = SettingsConfig(
        config_file='config.toml',
    )

settings = Settings()
print(settings)
# app_id='1' app_name='Python Application' description='Test application description' log_level='INFO'

---

Loading Multiple Config Files

Multiple config files can be loaded by passing a list of file names. Files will be loaded in the order they are listed. Meaning later files in the list will take priority over earlier files.

config.toml

app_name = "Python Application"
description = "Test application description"

config.json

{
  "description": "Description from JSON file",
  "log_level": "WARNING"
}

settings.py

from pydantic_config import SettingsModel, SettingsConfig

class Settings(SettingsModel):
    app_id: str = 1
    app_name: str = 'App Name'
    description: str = None
    log_level: str = 'INFO'
    
    model_config = SettingsConfig(
        config_file=['config.toml', 'config.json']  # The config.json file will take priority over config.toml
    )

settings = Settings()
print(settings)
# app_id='1' app_name='Python Application' description='Description from JSON file' log_level='WARNING'

---

Supported File Formats

Currently, the following file formats are supported:

• .yaml Requires pyyaml package
• .toml Requires tomli package for python<3.11
• .json
• .ini

---

Using .env files

Since Pydantic natively supports dotenv files, you can combine a .env file with config files easily.
Values from the .env file take precedence over config files.

from pydantic_config import SettingsModel, SettingsConfig

class Settings(SettingsModel):
  app_name: str = None
  description: str = None
    
    model_config = SettingsConfig(
        env_file='.env',
        config_file='config.toml',
    )

---

Requiring Config Files to Exist

By default, missing config files are ignored (no error is raised). This may be useful if you want to specify config files that may not always exist. For example, you might have different config files for per environment: config-prod.toml and config-dev.toml.

To enforce that config files must exist, set config_file_required=True. This will cause an error to be raised if the specified config file(s) does not exist.

model_config = SettingsConfig(
    config_file='config.toml',
    config_file_required=True,
)

⚠️ When config_file_required=True, config_file cannot be None or an empty list [].

---

Merging

By default, when merging multiple config files:

• dict values are merged (keys combined).
• list values are merged (items combined).

To disable merging and prefer overwriting entirely, set config_merge=False.

Example:

config.toml

[foo]
item1 = "value1"

config2.toml

[foo]
item2 = "value2"

settings.py

from pydantic_config import SettingsModel, SettingsConfig

class Settings(SettingsModel):
    foo: dict = {}

    model_config = SettingsConfig(
        config_file=['config.toml', 'config2.toml'],
        config_merge=True,
    )

settings = Settings()
print(settings)
# foo={'item1': 'value1', 'item2': 'value2'}

If config_merge=False, the second file would overwrite the first:

foo={'item2': 'value2'}

---

Handling Duplicates in Merged Lists

By default, merged lists include all items, even duplicates.

To ensure list items are unique during merge, set config_merge_unique=True.

model_config = SettingsConfig(
    config_file=['config1.toml', 'config2.toml'],
    config_merge=True,
    config_merge_unique=True,
)

License

This project is licensed under the MIT License.