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

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

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

Filename, Size & Hash SHA256 Hash Help File Type Python Version Upload Date
(13.8 kB) Copy SHA256 Hash SHA256
Wheel py2.py3 Apr 5, 2017
(17.9 kB) Copy SHA256 Hash SHA256
Source None Apr 5, 2017

Supported By

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 Google Google Cloud Servers