A thin wrapper over Pydantic’s settings management. Allows you to define configuration variables and load them from environment or JSON/YAML/TOML file. Also generates initial configuration files and documentation for your defined configuration.
Installation
pip install goodconf or pip install goodconf[yaml] / pip install goodconf[toml] if parsing/generating YAML/TOML files is required. When running on Python 3.11+ the [toml] extra is only required for generating TOML files as parsing is supported natively.
Quick Start
Let’s use configurable Django settings as an example.
First, create a conf.py file in your project’s directory, next to settings.py:
import base64
import os
from goodconf import GoodConf, Field
from pydantic import PostgresDsn
class AppConfig(GoodConf):
"Configuration for My App"
DEBUG: bool
DATABASE_URL: PostgresDsn = "postgres://localhost:5432/mydb"
SECRET_KEY: str = Field(
initial=lambda: base64.b64encode(os.urandom(60)).decode(),
description="Used for cryptographic signing. "
"https://docs.djangoproject.com/en/2.0/ref/settings/#secret-key")
model_config = {"default_files": ["/etc/myproject/myproject.yaml", "myproject.yaml"]}
config = AppConfig()Next, use the config in your settings.py file:
import dj_database_url
from .conf import config
config.load()
DEBUG = config.DEBUG
SECRET_KEY = config.SECRET_KEY
DATABASES = {"default": dj_database_url.parse(config.DATABASE_URL)}In your initial developer installation instructions, give some advice such as:
python -c "import myproject; print(myproject.conf.config.generate_yaml(DEBUG=True))" > myproject.yamlBetter yet, make it a function and entry point so you can install your project and run something like generate-config > myproject.yaml.
Usage
GoodConf
Your subclassed GoodConf object can include a model_config dictionary with the following attributes:
- file_env_var
The name of an environment variable which can be used for the name of the configuration file to load.
- default_files
If no file is passed to the load method, try to load a configuration from these files in order.
It also has one method:
- load
Trigger the load method during instantiation. Defaults to False.
Use plain-text docstring for use as a header when generating a configuration file.
Environment variables always take precedence over variables in the configuration files.
See Pydantic’s docs for examples of loading:
Fields
Declare configuration values by subclassing GoodConf and defining class attributes which are standard Python type definitions or Pydantic FieldInfo instances generated by the Field function.
Goodconf can use one extra argument provided to the Field to define an function which can generate an initial value for the field:
- initial
Callable to use for initial value when generating a config
Django Usage
Install with the django extra to pull in Django for the helper below:
pip install goodconf[django]
A helper is provided which monkey-patches Django’s management commands to accept a --config argument. Replace your manage.py with the following:
# Define your GoodConf in `myproject/conf.py`
from myproject.conf import config
if __name__ == '__main__':
config.django_manage()Why?
I took inspiration from logan (used by Sentry) and derpconf (used by Thumbor). Both, however used Python files for configuration. I wanted a safer format and one that was easier to serialize data into from a configuration management system.
Environment Variables
I don’t like working with environment variables. First, there are potential security issues:
Accidental leaks via logging or error reporting services.
Child process inheritance (see ImageTragick for an idea why this could be bad).
Second, in practice on deployment environments, environment variables end up getting written to a number of files (cron, bash profile, service definitions, web server config, etc.). Not only is it cumbersome, but also increases the possibility of leaks via incorrect file permissions.
I prefer a single structured file which is explicitly read by the application. I also want it to be easy to run my applications on services like Heroku where environment variables are the preferred configuration method.
This module let’s me do things the way I prefer in environments I control, but still run them with environment variables on environments I don’t control with minimal fuss.
Contribute
Install dependencies.
uv syncRun the tests against your environment:
uv run pytestOr run the full matrix with tox (installed with the tox-uv plugin):
uv tool install tox --with tox-uv
toxTested versions
CI runs two dependency stacks (see tox.ini): the minimum supported versions (pydantic 2.7, pydantic-settings 2.13, ruamel.yaml 0.17, tomlkit 0.11, Django 5.2) on the older Pythons, and the latest releases on the newer ones.
Python |
Django |
deps |
|---|---|---|
3.10 |
5.2 |
minimum |
3.11 |
5.2 |
minimum |
3.12 |
6.0 |
latest |
3.13 |
6.0 |
latest |
3.14 |
6.0 |
latest |
dev also runs the exact versions pinned in uv.lock; mypy type-checks.
Releases are done with GitHub Actions whenever a new tag is created. For more information, see ./.github/workflows/build.yml
1 maintainer
Metadata
1 maintainer
Release files for goodconf 7.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| goodconf-7.1.0.tar.gz | 67.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| goodconf-7.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 79.1 kB
Release files / goodconf-7.1.0.tar.gz
| Download URL | goodconf-7.1.0.tar.gz |
|---|---|
| Size | 67.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b000fdd93e931257648523bc2c15a32406c54223936b2fccca767cb9a94b13f9
|
|
BLAKE2b-256 checksum How to use checksums |
364c44d167ec9de9b5d256ebb3ef0a3a5d4b69e366cc96835bdc5de006545019
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 17, 2026.
Transparency logRelease files / goodconf-7.1.0-py3-none-any.whl
| Download URL | goodconf-7.1.0-py3-none-any.whl |
|---|---|
| Size | 11.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cf622f9501ef90f90de231e8804a1436123fb2098cd4bc5805aab8c038fca9ea
|
|
BLAKE2b-256 checksum How to use checksums |
51c97a4ad029d73f70293ed369b367bd91337d6f898e0c3a88c9607838afeb4a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 17, 2026.
Transparency log
