envparse2 is a simple utility to parse environment variables.

NOTE: envparse2 is a fork of envparse which is no longer maintained, to check original author and code visit <https://github.com/rconradharris/envparse.git>

If you use Heroku and/or subscribe to the tenets of the 12 Factor App you’ll be using a lot of environment variable-based configuration in your app. os.environ is a great choice to start off with but over time you’ll find yourself duplicating quite a bit of code around handling raw environment variables.

envparse2 aims to eliminate this duplicated, often inconsistent parsing code and instead provide a single, easy-to-use wrapper.

Ideas, and code portions, have been taken from django-environ project but made framework agnostic.

Installing

Through PyPI:

$ pip install envparse2

Usage

In your settings or configuration module, first either import the standard parser or one with a schema:

# Standard
from envparse2 import env

# Schema
from envparse2 import Env
env = Env(BOOLEAN_VAR=bool, LIST_VAR=dict(cast=list, subcast=int))

env can then be called in two ways:

  • Type explicit: env('ENV_VAR_NAME', cast=TYPE, ...)

  • Type implicit (for Python builtin types only): env.TYPE('ENV_VAR_NAME', ...) If type is not specified, explicitly or implicitly, then the default type is str.

Casting to a specified type:

# Environment variable: MAIL_ENABLED=1

mail_enabled = env('MAIL_ENABLED', cast=bool)
# OR mail_enabled = env.bool('MAIL_ENABLED')
assert mail_enabled is True

Casting nested types:

# Environment variable: FOO=1,2,3
foo = env('FOO'), subcast=int)
# OR: foo = env('FOO', cast=list, subcast=int)
# Note that there is no way to implicitly call subcast.
assert foo == [1, 2, 3]

Specifying defaults:

# Environment variable MAX_ROWS has not been defined

max_rows = env.int('MAX_ROWS', default=100)
assert max_rows == 100

Proxying values, useful in Heroku for wiring up the environment variables they provide to the ones that your app actually uses:

# Environment variables: MAILGUN_SMTP_LOGIN=foo,
# SMTP_LOGIN='{{MAILGUN_SMTP_LOGIN}}'

smtp_login = env('SMTP_LOGIN')
assert smtp_login == 'foo'

Now if you switch to using Mandrill as an email provider, instead of having to modify your app, you can simply make a configuration change:

SMTP_LOGIN='{{MANDRILL_UESRNAME}}'

There are also a few convenience methods:

  • env.json: parses JSON and returns a dict.

  • env.url: parses a url and returns a urlparse.ParseResult object.

Type specific notes:

  • list: the expected environment variable format is FOO=1,2,3 and may contain spaces between the commas as well as preceding or trailing whitespace.

  • dict: the expected environment variable format is FOO='key1=val1, key2=val2. Spaces are also allowed.

  • json: a regular JSON string such as FOO='{"foo": "bar"}' is expected.

Schemas

Define a schema so you can only need to provide the cast, subcast, and defaults once:

# Environment variables: MAIL_ENABLED=0, LIST_INT='1,2,3'

# Bind schema to Env object to get schema-based lookups
env = Env(MAIL_ENABLED=bool, SMTP_LOGIN=dict(cast=str, default='foo'),
          LIST_INT=dict(cast=list, subcast=int))
assert env('MAIL_ENABLED') is False
assert env('SMTP_LOGIN') == 'foo' # Not defined so uses default
assert env('LIST_INT') == [1, 2, 3]

The Env constructor takes values in the form of either: VAR_NAME=type or VAR_NAME=dict where dict is a dictionary with either one or more of the following keys specified: cast, subcast, default.

Pre- and Postprocessors

Preprocessors are callables that are run on the environment variable string before any type casting takes place:

# Environment variables: FOO=bar

# Preprocessor to change variable to uppercase
to_upper = lambda v: v.upper()
foo = env('FOO', preprocessor=to_upper)
assert foo == 'BAR'

Postprocessors are callables that are run after the type casting takes place. An example of one might be returning a datastructure expected by a framework:

# Environment variable: REDIS_URL='redis://:redispass@127.0.0.1:6379/0'
def django_redis(url):
  return {'BACKEND': 'django_redis.cache.RedisCache',
      'LOCATION': '{}:{}:{}'.format(url.hostname, url.port, url.path.strip('/')),
      'OPTIONS': {'PASSWORD': url.password}}

redis_config = env('REDIS_URL', postprocessor=django_redis)
assert redis_config == {'BACKEND': 'django_redis.cache.RedisCache',
    'LOCATION': '127.0.0.1:6379:0', 'OPTIONS': {'PASSWORD': 'redispass'}}

Environment File

Read from a .env file (line delimited KEY=VALUE):

# This recurses up the directory tree until a file called '.env' is found.
env.read_envfile()

# Manually specifying a path
env.read_envfile('/config/.myenv')

# Values can be read as normal
env.int('FOO')

Project links

Data verified by PyPI on Sep 6, 2025
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for beregond from gravatar.com beregond

Credits

PyPI data
Data sourced directly from PyPI's database.

Maintainer: Szczepan Cieślik

Author: Rick Harris

GitHub Statistics

Data verified by PyPI on Sep 6, 2025
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Classifiers

Report project as malware

Download files

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

Source Distribution

envparse2-1.0.0.tar.gz (8.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

envparse2-1.0.0-py2.py3-none-any.whl (6.7 kB view details)

Uploaded Python 2Python 3

File details

Details for the file envparse2-1.0.0.tar.gz.

File metadata

  • Download URL: envparse2-1.0.0.tar.gz
  • Upload date:
  • Size: 8.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for envparse2-1.0.0.tar.gz
Algorithm Hash digest
SHA256 2103ab70c22a2df1104dbc9621aa51281fce087de7e48966f2892d8bff4b0aeb
MD5 92beb716580ef4f622e301b0d8ceeab4
BLAKE2b-256 f608815cbdd6eedbe72bc9e655fa390313e1896ea426d57639c5f36c3a72b9da

See more details on using hashes here.

Provenance

The following attestation bundles were made for envparse2-1.0.0.tar.gz:

Publisher: release.yml on beregond/envparse2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file envparse2-1.0.0-py2.py3-none-any.whl.

File metadata

  • Download URL: envparse2-1.0.0-py2.py3-none-any.whl
  • Upload date:
  • Size: 6.7 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for envparse2-1.0.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 102f5993c4724357e5f7a4acccebf9431a784eaaed3a45cbf7569b9983483df0
MD5 eabe87af344a7a9db5bda5d4540cee55
BLAKE2b-256 fe7a30ce6dc97358b62fb074b001bf6e987c8e50f541ee4c43f360ded57fe23e

See more details on using hashes here.

Provenance

The following attestation bundles were made for envparse2-1.0.0-py2.py3-none-any.whl:

Publisher: release.yml on beregond/envparse2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 files

0.3.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page