Easy access of environment variables from Python with support for strings, booleans, list, tuples, and dicts.

environment variables, boolean, dict, environment-variables, lists, python, strings, tuples
pip install envs==1.3



Easy access of environment variables from Python with support for booleans, strings, lists, tuples, integers, floats, and dicts.

Use Case

If you need environment variables for your settings but need an easy way of using Python objects instead of just strings. For example, if you need a list of strings.


  • CLI to convert settings
  • CLI to list and check environment variables
  • Use strings, lists, tuples, integers, floats or dicts. IMPORTANT: When setting the variables in your environmenet (ex. in .env file) wrap them in single or double quotes (ex. "['some','list']")

Build Status

Quick Start


Install without CLI Requirements

pip install envs

Install with CLI Requirements

pip install envs["cli"]

Run Convert Settings

IMPORTANT: Don't name this file the same as the original module (you have added the imports back yet).

envs convert_settings --settings-file your.settings.module

Copy and Paste the Imports and Logic Code From Original File

Envs does not copy and paste your imports from your original code, so you have to do this manually.

Run List Envs

This tells you what envs have default v

envs list_envs --settings-file your.settings.module

General API

from envs import env

env('SOMEVAR','default value for that var',var_type='string',allow_none=True)


Environment Variable Example: SECRET_KEY='adfadfadfafasf'

>>>from envs import env

>>>env('SECRET_KEY','default secret key here')


Environment Variable Example: SERVER_NAMES="['coastal','inland','western']"

>>>from envs import env



Environment Variable Example: SERVER_NAMES="('coastal','inland','western')"

>>>from envs import env



Environment Variable Example: DATABASE="{'USER':'name','PASSWORD':'password'}"

>>>from envs import env



Environment Variable Example: NO_SERVERS=12

>>>from envs import env



Environment Variable Example: INDEX_WEIGHT=0.9

>>>from envs import env



Environment Variable Example: USE_PROFILE=false

>>>from envs import env



Environment Variable Example: HALF_SEVEN=3.5

>>> from envs import env

>>> env('HALF_SEVEN', var_type='decimal')

Command Line Utils

IMPORTANT: All of the command arguments will fallback to becoming prompts if not set when calling the commands.

Convert Module (convert_module)

Converts an existing settings file so it uses envs. IMPORTANT: This command does not copy your import stataements to the new module.


  • settings-file: - Dot notated import string for settings file
envs convert_module --settings-file your.settings

List Envs (list_envs)

Shows a list of env instances set in a settings file.

  • settings-file: - Dot notated import string for settings file
  • keep-result: - Keep the .env_results file generated by this command (default: False)
envs list_envs --settings-file your.settings --keep-result False

Check Envs (check_envs)

Make sure that the defined envs with no default value have a value set in the environment. This command will raise an EnvsValueException if there is environment variable that should be set that is not. This command is meant for use with a CI/CD tool as a way to halt the build if there isn't a value for an environment variable.

  • settings-file: - Dot notated import string for settings file
envs check_envs --settings-file your.settings


Twitter::@brianjinwright Github: bjinwright