Skip to main content

manage user configuration for python packages

Project description

manage user configuration for python projects

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:

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 new (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"
    general = Section(
            doc="your name",
            default="unknown person"),
            doc="your age",
    address = Section(
            doc="street including house number",
        doc="shipping address")

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

Command line help text:

$ python examples/ -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/ --age 211
hello there, unknown person!

Command line use without required value:

$ python examples/
Traceback (most recent call last):
  File "examples/", line 26, in <module>
    CONFIG = MyConfig()
  File "/git/user_config/user_config/user_config/", line 541, in __init__
  File "/git/user_config/user_config/user_config/", line 322, in validate_data
  File "/git/user_config/user_config/user_config/", line 216, in validate_data
user_config.MissingData: no value was provided for required option age

Command line use:

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

Generate configuration file:

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

## shipping address

# city =
city =

## street including house number
# street =
street =

## your age
# age =
age =

## your name
# name = unknown person

Planned features

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for user-config, version 1.0a4
Filename, size File type Python version Upload date Hashes
Filename, size user_config-1.0a4-py2.py3-none-any.whl (11.3 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size user_config-1.0a4.tar.gz (406.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page