Welcome to user_config’s documentation!

manage user configuration for python projects


Indices and tables


Manage user configuration for python projects.

For easy and well-documented user-defined configuration.


  • Documentation Status
  • https://travis-ci.org/nihlaeth/user_config.svg?branch=master
  • https://api.codacy.com/project/badge/Grade/bd13a0474ea44c8e8a95e10ef4d89585
  • https://api.codacy.com/project/badge/Coverage/bd13a0474ea44c8e8a95e10ef4d89585
  • https://img.shields.io/github/tag/nihlaeth/user_config.svg
  • https://img.shields.io/pypi/v/user_config.svg
  • https://img.shields.io/pypi/l/user_config.svg
  • https://img.shields.io/pypi/pyversions/user_config.svg
  • https://img.shields.io/pypi/status/user_config.svg

Fallback order

  1. command line arguments
  2. user config files in ~/.config/<app>/config.<extension>
  3. global config files in /etc/xdg/<app>/config.<extension>
  4. default values

For directories on operating systems than linux, see: https://github.com/ActiveState/appdirs

Config format

Supported out of the box: ini

Other config formats can be supported via plug-ins.


  • Linux, or Os X, or Windows (but not Windows Vista)
  • python 2.7 or newer (python 3.6 supported)
  • relatively new versions of setuptools and pip (version requirement to follow)


Simple configuration example

"""Usage example for user_config."""
from user_config import Config, Section, StringOption, IntegerOption

class MyConfig(Config):

    """This will be displayed in the configuration documentation."""

    application = "my_application"
    author = "me"

    class GeneralSection(Section):
        """General information."""
        name = StringOption(
            doc="your name",
            default="unknown person")
        age = IntegerOption(
            doc="your age",
    general = GeneralSection()
    class AddressSection(Section):
        """shipping address"""
        street = StringOption(
            doc="street including house number",
        city = StringOption(required=True)
    address = AddressSection(required=False)

if __name__ == "__main__":
    CONFIG = MyConfig()
    print("hello there, {}!".format(CONFIG.general.name))

Command line help text:

$ python examples/simple_example.py -h
usage: my_application [-h] [--generate-config] [--city CITY] [--street STREET]
                      [--age AGE] [--name NAME]

This will be displayed in the configuration documentation. Command line
arguments overwrite configuration found in:
/root/.config/my_application/config.cfg /etc/xdg/my_application/config.cfg

optional arguments:
  -h, --help         show this help message and exit
  --generate-config  print a complete configuration file with current settings
  --city CITY
  --street STREET    street including house number
  --age AGE          your age
  --name NAME        your name

Command line use with default value:

$ python examples/simple_example.py --age 211
hello there, unknown person!

Command line use without required value:

$ python examples/simple_example.py
Traceback (most recent call last):
  File "examples/simple_example.py", line 29, in <module>
    CONFIG = MyConfig()
  File "/git/user_config/user_config/user_config/__init__.py", line 622, in __init__
  File "/git/user_config/user_config/user_config/__init__.py", line 464, in validate_data
  File "/git/user_config/user_config/user_config/__init__.py", line 380, in validate_data
user_config.MissingData: no value was provided for required option age

Command line use:

$ python examples/simple_example.py --age 211 --name mystery_user
hello there, mystery_user!

Generate configuration file:

$ python examples/simple_example.py --generate-config
## This will be displayed in the configuration documentation.

## General information.

## your name
# name = unknown person
name = tamara

## your age
# age =
age =

## shipping address

## street including house number
# street =
street =

# city =
city =


$ pip install -e ".[doc]"
$ python setup.py build_sphinx


  • pytest
  • pytest-cov
  • coverage
  • codacy-coverage
$ python -m pytest --cov=user_config --cov-report xml

Planned features

  • multi matching sections / wildcard sections
  • yaml config format
  • json config format
  • hook for overwriting config from database or other storage function