Skip to main content

Boilerplate-free configuration with env variables.

Project description

CI status Test Coverage Code style: black

environ-config allows you to configure your applications using environment variables – as recommended in The Twelve-Factor App methodology – with elegant, boilerplate-free, and declarative code:

>>> import environ
>>> # Extracts secrets from Vault-via-envconsul: 'secret/your-app':
>>> vault = environ.secrets.VaultEnvSecrets(vault_prefix="SECRET_YOUR_APP")
>>> @environ.config(prefix="APP")
... class AppConfig:
...    @environ.config
...    class DB:
...        name = environ.var("default_db")
...        host = environ.var("")
...        port = environ.var(5432, converter=int)  # Use attrs's converters and validators!
...        user = environ.var("default_user")
...        password = vault.secret()
...    env = environ.var()
...    lang = environ.var(name="LANG")  # It's possible to overwrite the names of variables.
...    db =
...    awesome = environ.bool_var()
>>> cfg = environ.to_config(
...     AppConfig,
...     environ={
...         "APP_ENV": "dev",
...         "APP_DB_HOST": "localhost",
...         "LANG": "C",
...         "APP_AWESOME": "yes",  # true and 1 work too, everything else is False
...         # Vault-via-envconsul-style var name:
...         "SECRET_YOUR_APP_DB_PASSWORD": "s3kr3t",
... })  # Uses os.environ by default.
>>> cfg
AppConfig(env='dev', lang='C', db=AppConfig.DB(name='default_db', host='localhost', port=5432, user='default_user', password=<SECRET>), awesome=True)
>>> cfg.db.password

AppConfig.from_environ({...}) is equivalent to the code above, depending on your taste.

@environ.config(from_environ="different_name_for_from_environ", generatef_help="different_name_for_generate_help") allows to rename generated classmethods or to prevent it’s creation by passing None instead of a name.


  • Declarative & boilerplate-free.

  • Nested config from flat env variable names.

  • Default & mandatory values: enforce configuration structure without writing a line of code.

  • Helpful debug logging that will tell you which variables are present and what environ-config is looking for.

  • Built on top of attrs which gives you data validation and conversion for free.

  • Pluggable secrets extraction. Ships with:

  • Pass any dict into environ.to_config(AppConfig, {"your": "config"}) instead of loading from the environment.

  • Built in dynamic help documentation generation via environ.generate_help.

>>> import environ
>>> @environ.config(prefix="APP")
... class AppConfig:
...     @environ.config
...     class SubConfig:
...         sit = environ.var(help="Another example message.")
...         amet = environ.var()
...     lorem = environ.var('ipsum')
...     dolor = environ.bool_var(True, help="An example message.")
...     subconfig =
>>> print(environ.generate_help(AppConfig))
APP_LOREM (Optional)
APP_DOLOR (Optional): An example message.
APP_SUBCONFIG_SIT (Required): Another example message.
>>> print(environ.generate_help(AppConfig, display_defaults=True))
APP_LOREM (Optional, Default=ipsum)
APP_DOLOR (Optional, Default=True): An example message.
APP_SUBCONFIG_SIT (Required): Another example message.

AppConfig.generate_help({...}) is equivalent to the code above, depending on your taste.

Project Information

environ-config is released under the Apache License 2.0 license. It targets Python 2.7, 3.5 and newer, and PyPy.

Release Information

19.1.0 (2019-09-02)

Backward-incompatible changes:

  • Changed license from MIT to Apache License 2.




  • Added AppConfig.from_environ() to instantiate the config class. This is an alternative to environ.from_environ(AppConfig). #5

  • Added environ.generate_help(AppConfig) and AppConfig.generate_help() to create a help string based on the configuration.

  • environ.config(from_environ="fr_env", generate_help="gen_hlp") allows passing alternative names for class methods "from_environ" and "generate_help", or prevent their creation by pasing None. #7

  • If environ.var is passed an attr.Factory, the callable is used to generate the default value. #10

Full changelog.


environ_config is written and maintained by Hynek Schlawack.

The development is kindly supported by Variomedia AG.

A full list of contributors can be found in GitHub’s overview.

environ_config wouldn’t be possible without the attrs project.

Project details

Download files

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

Source Distribution

environ-config-19.1.0.tar.gz (19.9 kB view hashes)

Uploaded Source

Built Distribution

environ_config-19.1.0-py2.py3-none-any.whl (13.7 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page