Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

manage user configuration for python packages

Project Description


Manage user configuration for python projects.

For easy and well-documented user-defined configuration.

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 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(

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 29, in <module>
    CONFIG = MyConfig()
  File "/git/user_config/user_config/user_config/", line 622, in __init__
  File "/git/user_config/user_config/user_config/", line 464, in validate_data
  File "/git/user_config/user_config/user_config/", line 380, 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.

## 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 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
Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
user_config-1.0a10-py2.py3-none-any.whl (13.8 kB) Copy SHA256 Checksum SHA256 py2.py3 Wheel Apr 5, 2017
user_config-1.0a10.tar.gz (17.9 kB) Copy SHA256 Checksum SHA256 Source Apr 5, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting