Skip to main content

Jinja2 templating based on environment variables.

Project description

Jinja 2 Command Line Template Renderer

Build Status

Jinja2 command line renderer that converts environment variables into objects on the context. For example:



    "database": {
        "main": {
            "uri": "mysql:3306",
            "username": "app"
        "cache": {
            "uri": "redis:6379",
            "username": "app"

This allows using things like iterations and others for more dynamic templates.

While there are several command line Jinja2 template renderers, they all share a single property that this attempts to solve.

Of those that support environment variables (for Docker, typically), those environment variables are presented to the template verbatum. That is, given this environment:


A template would have to use them in the following way:

databases: {
    main: {
        uri: {{ DATABASE_MAIN_URI }}
        username: {{ DATABASE_MAIN_USERNAME }}
    cache: {
        uri: {{ DATABASE_CACHE_URI }}
        username {{ DATABASE_CACHE_USERNAME }}

Suppose, though, that you don't necessarily know how many databases your container will have? This construct makes it diffcult in those instances where you have to define N things differently depending on a container deployment, or for base images.

databases: {
    {% for name,definition in databases.items() %}
    {{ name }}: {
        uri: {{ definition.uri }},
        username: {{ definition.username }}
    {% endfor %}

Handling Collisions

Environment variables can sometimes cause interesting problems when building a tree structure. A ValueError will be thrown if a variable is defined twice. Howver, the following is a valid set of environment variables:


In the template context, {{ auth.ldap }} has to be an object as username is a key inside of it. In this case, the value of AUTH_LDAP will be moved down into a special _ key. The two variables would then be:

{{ auth.ldap._ }}=true
{{ auth.ldap.username }}=app

For this to work, almost all _ in environment keys are removed. So, AUTH__LDAP_ is still translated to {{ auth.ldap }}. The only exception is a variable with just underscores. In this case, a '_' is added to the root of the context with that value. Note that all of the following would create this single underscore value:

  • _
  • ___
  • ____________________

If multiple solely-underscore environment variables exist, a ValueError is thrown.


This can be installed in two ways:

  1. pip3 install j2tmpl
  2. Download the prebuilt binaries.

Note that the prebuilt binaries include the entire Python interpreter so they can be used just as easily as confd.


This can be used in two ways: processing a single file, or an entire directory.

When a directory path is passed as the template file, j2tmpl will scan the directory for any files with an extension matching template-extensions, an argument that defaults to tmpl,jinja,jinja2,j2,jnj.

Note that it will still output to stdout unless -o is used. If it is, then make sure it's a directory as well. If the target directory doesn't exist, it will be created.

In addition to files matching that pattern, any directory that matches that pattern and also ends with .d will be scanned for template fragments. Template files as well as files in .d directories that end in those extensions will all be concatenated together and rendered into one output file that matches the name of the directory without the template extension and without .d.

For example, given the following directory structure:


The output directory will contain the following:


Built-In Filters and extensions

Jinja's do and loopcontrols extensions are enabled by default as are the trim_blocks and lstrip_blocks

Finally, the following additionals filters are avilable:

readfile(str): Read in the contents of the file represented by str. This is particularly useful for container secrets.

boolean(str): Convert the argument into a boolean. A case insensitive comparison to "true", "yes", "on", and "1" will return True. Everything else is false.

b64encode(str): Base 64 encode the value.

b64decode(str): Base 64 decode the value.

Why not confd?

Speaking of confd, why not just use it? While confd is great, it can be a bit too verbose. Having to define a series of config files with all keys enurmated for every single key can be daunting. For certain projects, it probably makes sense, but I would often like to just barf some environment variables into a configuration file with only a tiny amount complexity.

confd is a 5.5mb or so binary and this is still less than 15mb. There are likely ways to make this smaller that I would love to explore.

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

j2tmpl-0.0.13.tar.gz (7.8 kB view hashes)

Uploaded source

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