API Reference

environ.config(maybe_cls=None, prefix='APP', from_environ='from_environ', generate_help='generate_help', frozen=False)

Make a class a configuration class.

  • prefix (str) – The prefix that is used for the env variables. If you have an var attribute on the class and your leave the default prefix of APP, environ-config will look for an environment variable called APP_VAR.

  • from_environ (str) – If not None, attach a config loading method with the name from_environ to the class. See to_config for more information.

  • generate_help (str) – If not None, attach a config loading method with the name generate_help to the class. See generate_help for more information.

  • frozen (bool) – The configuration will be immutable after instantiation, if True.

New in version 19.1.0: from_environ

New in version 19.1.0: generate_help

New in version 20.1.0: frozen

environ.var(default=Raise(), converter=None, name=None, validator=None, help=None)

Declare a configuration attribute on the body of config-decorated class.

It will be attempted to be filled from an environment variable based on the prefix and name.

  • default – Setting this to a value makes the config attribute optional.

  • name (str) – Overwrite name detection with a string. If not set, the name of the attribute is used.

  • converter – A callable that is run with the found value and its return value is used. Please not that it is also run for default values.

  • validator – A callable that is run with the final value. See attrs’s chapter on validation for details. You can also use any validator that is shipped with attrs.

  • help (str) – A help string that is used by generate_help.

environ.bool_var(default=Raise(), name=None, help=None)

Like var, but converts the value to a bool.

The following values are considered True:

  • True (if you set a default)

  • "1"

  • "true"

  • "yes"

Every other value is interpreted as False. Leading and trailing whitespace is ignored.


A configuration attribute that is another configuration class.

This way you can nest your configuration hierarchically although the values are coming from a flat source.

The group’s name is used to build a namespace:

class Cfg:
    class Sub:
        x = environ.var()

    sub = environ.group(Sub)

The value of x is looked up using APP_SUB_X.

You can nest your configuration as deeply as you wish.

environ.to_config(config_cls, environ=os.environ)

Load the configuration as declared by config_cls from environ.

  • config_cls – The configuration class to fill.

  • environ (dict) – Source of the configuration. os.environ by default.


An instance of config_cls.

This is equivalent to calling config_cls.from_environ().

environ.generate_help(config_cls, formatter=None, **kwargs)

Autogenerate a help string for a config class.

  • formatter – A callable that will be called with the help dictionaries as an argument and the remaining kwargs. It should return the help string.

  • display_defaults (bool) – When using the default formatter, passing True for display_defaults makes the default values part of the output.


A help string that can be printed to the user.

This is equivalent to calling config_cls.generate_help().

New in version 19.1.0.


Handling of sensitive data.

class environ.secrets.INISecrets(section, cfg=None, env_name=None, env_default=None)

Load secrets from an INI file using configparser.RawConfigParser.

classmethod from_path(path, section='secrets')

Look for secrets in section of path.

  • path (str) – A path to an INI file.

  • section (str) – The section in the INI file to read the secrets from.

classmethod from_path_in_env(env_name, default=None, section='secrets')

Get the path from the environment variable env_name at runtime and then load the secrets from it.

This allows you to overwrite the path to the secrets file in development.

  • env_name (str) – Environment variable that is used to determine the path of the secrets file.

  • default (str) – The default path to load from.

  • section (str) – The section in the INI file to read the secrets from.

secret(default=Raise(), converter=None, name=None, section=None, help=None)

Declare a secret on an environ.config-decorated class.


section (str) – Overwrite the section where to look for the values.

Other parameters work just like in environ.var.

class environ.secrets.VaultEnvSecrets(vault_prefix)

Loads secrets from environment variables that follow the naming style from envconsul.

secret(default=Raise(), converter=None, name=None, help=None)

Almost identical to environ.var except that it takes envconsul naming into account.


Exceptions raised by environ-config.

exception environ.exceptions.MissingEnvValueError

A mandatory environment variable can’t be found.

exception environ.exceptions.MissingSecretError

A mandatory secret can’t be found.