Installation#

Requirements#

Python 3.7 to 3.11 supported.

Django 3.2 to 4.1 supported.

Installation#

  1. Install with pip:

    python -m pip install django-htmx
    
  2. Add django-htmx to your INSTALLED_APPS:

    INSTALLED_APPS = [
        ...,
        "django_htmx",
        ...,
    ]
    
  3. Add the middleware:

    MIDDLEWARE = [
        ...,
        "django_htmx.middleware.HtmxMiddleware",
        ...,
    ]
    

    The middleware adds request.htmx, as described in Middleware.

  4. (Optional) Add the extension script to your base template, as documented in Extension Script.

Install htmx#

django-htmx does not include htmx itself, since it can work with many different versions. It’s up to you to add htmx (and any extensions) to your project.

Warning

JavaScript CDN’s

Avoid using JavaScript CDN’s like unpkg.com to include htmx (or any resources). They reduce privacy, performance, and security - see this post.

You can add htmx like so:

  1. Download htmx.min.js from its latest release.

  2. Put htmx.min.js in a static directory in your project. For example, if you have a static/ directory in your STATICFILES_DIRS setting:

    STATICFILES_DIRS = [BASE_DIR / "static"]
    

    …then put it in there, organized as you like, such as in a js/ sub-directory.

  3. Add a <script> tag in your base template, within your <head>:

    {% load static %}
    <script src="{% static 'htmx.min.js' %}" defer></script>
    

    (or js/htmx.min.js, etc.).

    The defer attribute allows the browser to continue rendering the page whilst htmx is downloading, making your site’s first render faster.

    If you have multiple base templates for pages that you want htmx on, add the <script> on all of them.

Note

Extensions

You can adapt the above steps to set up htmx’s extensions that you wish to use. Download them from htmx’s ext/ folder into your project, and include their script tags after htmx, for example:

{% load static %}
<script src="{% static 'js/htmx/htmx.min.js' %}" defer></script>
<script src="{% static 'js/htmx/debug.js' %}" defer></script>