django-handlebars is a helper to use Handlebars client-side templates with Django.


pip install hg+


  1. add django_handlebars to INSTALLED_APPS
  2. put your handlebars templates in a folder named hbtemplates inside your app directory. Example:
  1. add {% load handlebars %} at the top of the template, and include the loader tag {% handlebars myapp %} into <head>. Note: you also need to include handlebars.js, of course

  2. use client-side templating like this:

    $('#result').html(Handlebars.templates['myapp.texts.text1.html']({context: 'context'});

How it works

django-handlebars takes everything under appdirectory/hbtemplates puts it into <script type="text/x-handlebars-template"> tags and adds these to the page. Also, a little glue script is added to compile the templates on page load and make them available under Handlebars.templates[...].

Precompiling templates

Since compiling templates on the fly inflates the DOM, works not well with browser caching and leads to increased load time, django-handlebars can also use Handlebars' precompilation feature.

To use it, install node.js and the Handlebars precompiler as described in Precompilation. Then add the path to the handlebars command to


Now, when django-handlebars encounters a {% handlebars %} tag, it will compile the templates to a single javascript file on the fly, and link it in the <head>. If the compiled file is already newer than the newest template, compilation will be skipped.

Additional compilation flags like -k, -o or -m can be used by adding them to settings.HANDLEBARS_COMPILATION_FLAGS (if present, this must be in form of an array, e.g. settings.HANDLEBARS_COMPILATION_FLAGS=['-m', '-k each', '-k if']).

django-handlebars stores precompiled template in its own static directory, so it will work out of the box when the built-in development server is used.

Precompiled templates in production

In production, precompiled templates can be served just like any other static file, and if you run the development server once, collectstatic will pick up the generated templates automatically. However, to avoid unneccessary runtime checks and compiler invocation, set settings.HANDLEBARS_PRODUCTION. If set to True (default is False) it will override any other setting and {% handlebars %} will directly add the <script> headers for precompiled templates without further checking or compilation.


django-handlebars is licensed under BSD License, which basically means you can use it wherever and however you see fit.

Reporting bugs

Use the bugtracker at