Library for managing environment variables in Clojure

License: EPL-1.0

Language: Clojure

Keywords: clojure, environment-variables


Environ is a Clojure library for managing environment settings from a number of different sources. It works well for applications following the 12 Factor App pattern.

Currently, Environ supports four sources, resolved in the following order:

  1. A .lein-env file in the project directory
  2. A .boot-env file on the classpath
  3. Environment variables
  4. Java system properties

The first two sources are set by the lein-environ and boot-environ plugins respectively, and should not be edited manually.

The .lein-env file is populated with the content of the :env key in the Leiningen project map. The .boot-env file is populated by the environ.boot/environ Boot task.


Include the following dependency in your project.clj file:

:dependencies [[environ "1.1.0"]]

If you want to be able to draw settings from the Leiningen project map, you'll also need the following plugin:

:plugins [[lein-environ "1.1.0"]]

If you are using the Boot toolchain, you may want to read and write settings from build pipelines. In build.boot, add the dependency:

:dependencies '[[boot-environ "1.1.0"]]

Then require the environ boot task.

(require '[environ.boot :refer [environ]])


Let's say you have an application that requires a database connection. Often you'll need three different databases, one for development, one for testing, and one for production.

Lets pull the database connection details from the key :database-url on the environ.core/env map.

(require '[environ.core :refer [env]])

(def database-url
  (env :database-url))

The value of this key can be set in several different ways. The most common way during development is to use a local profiles.clj file in your project directory. This file contained a map that is merged with the standard project.clj file, but can be kept out of version control and reserved for local development options.

{:dev  {:env {:database-url "jdbc:postgresql://localhost/dev"}}
 :test {:env {:database-url "jdbc:postgresql://localhost/test"}}}

In this case we add a database URL for the dev and test environments. This means that if you run lein repl, the dev database will be used, and if you run lein test, the test database will be used.

Keywords with a project namespace are looked up in the project map. For example:

{:env {:app-version :project/version}}

This looks up the :version key in the Leiningen project map. You can view the full project map by using lein-pprint.

In the case of Boot, you have the full flexibility of tasks and build pipelines, meaning that all the following are valid:

$ boot environ -e database-url=jdbc:postgresql://localhost/dev repl
(environ :env {:database-url "jdbc:postgresql://localhost/dev"})

The latter form can be included in custom pipelines and `task-options!'.

The task also creates or updates a .boot-env file in the fileset. This is useful for tasks that create their own pods like boot-test, which won't see changes in the environ vars.

When you deploy to a production environment, you can make use of environment variables, like so:

DATABASE_URL=jdbc:postgresql://localhost/prod java -jar standalone.jar

Or use Java system properties:

java -Ddatabase.url=jdbc:postgresql://localhost/prod -jar standalone.jar

Note that Environ automatically lowercases keys, and replaces the characters "_" and "." with "-". The environment variable DATABASE_URL and the system property database.url are therefore both converted to the same keyword :database-url.


Copyright © 2016 James Reeves

Distributed under the Eclipse Public License, the same as Clojure.

Project Statistics

Sourcerank 11
Repository Size 76.2 KB
Stars 696
Forks 56
Watchers 23
Open issues 15
Dependencies 0
Contributors 12
Tags 12
Last updated
Last pushed

Top Contributors See all

James Reeves Joe Littlejohn Daniel Compton Tim Visher Nuttanart Pornprasitsakul David Haslem Jean Niklas L'orange Charles (Cal) Loomis Earl St Sauver André-Marthin Helberg Antoine R. Dumont Daniel Szmulewicz

Packages Referencing this Repo

Library for accessing environment variables
Latest release 1.1.0 - Updated - 696 stars
Leiningen plugin for Environ
Latest release 1.1.0 - Updated - 696 stars
Boot task for Environ
Latest release 1.1.0 - Updated - 696 stars

Recent Tags See all

1.1.0 August 04, 2016
1.0.3 May 06, 2016
1.0.2 January 27, 2016
1.0.1 September 11, 2015
1.0.0 August 16, 2014
0.5.0 April 20, 2014
0.4.0 March 12, 2013
0.3.1 January 06, 2013
0.3.0 August 16, 2012
0.2.1 April 05, 2012
0.2.0 April 04, 2012
0.1.0 April 04, 2012

Something wrong with this page? Make a suggestion

Last synced: 2016-11-24 15:53:22 UTC

Login to resync this repository