Skip to content

Installation

Install django-tailwind-cli

  1. Install the library.
python -m pip install "django-tailwind-cli"

Add the optional libraries django-extensions and Werkzeug to use the extended debug server from django-extensions.

python -m pip install "django-tailwind-cli[django-extensions]"
  1. Add django_tailwind_cli to INSTALLED_APPS in settings.py.
INSTALLED_APPS = [
    # other Django apps
    "django_tailwind_cli",
]

If you want to use the extended debug server from django-extensions, add the package to the installed apps.

INSTALLED_APPS = [
    # other Django apps
    "django_tailwind_cli",
    "django_extensions",
]
  1. Configure the STATICFILES_DIRS parameter in your settings.py if not already configured.
STATICFILES_DIRS = [BASE_DIR / "assets"]
  1. Add template code.
{% load tailwind_cli %}
...
<head>
  ...
  {% tailwind_css %}
  ...
</head>
  1. Start the debug server or start the Tailwind CLI in watch mode.
python manage.py tailwind runserver

Or

python manage.py tailwind watch

If you only start the Tailwind CLI in watch mode, you have to start the debug server with the standard command python manage.py runserver seperately.

Optional steps

Install django-browser-reload

If you enjoy automatic reloading during development. Install the django-browser-reload app. The following installation steps are taken from the README of the project.

  1. Install django-browser-reload inside your Django project.
python -m pip install django-browser-reload

  1. Ensure you have django.contrib.staticfiles in your INSTALLED_APPS.

  2. Add django_browser_reload app to your INSTALLED_APPS.

INSTALLED_APPS = [
    ...,
    "django_browser_reload",
    ...,
]
  1. Include the app URL’s in your root URLconf(s).
from django.urls import include, path

urlpatterns = [
    ...,
    path("__reload__/", include("django_browser_reload.urls")),
]
  1. Add the middleware.
MIDDLEWARE = [
    # ...
    "django_browser_reload.middleware.BrowserReloadMiddleware",
    # ...
]

The middleware should be listed after any that encodes the response, such as Django’s GZipMiddleware.

The middleware automatically inserts the required script tag on HTML responses before when DEBUG is True. It does so to every HTML response, meaning it will be included on Django’s debug pages, admin pages, etc. If you want more control, you can instead insert the script tag in your templates—see below.

Upgrade from Tailwind CSS 3.x to 4.x

In order to upgrade this package from using Tailwind CSS 3.x to 4.x, you have to follow some simple steps.

  • Remove or change the setting TAILWIND_CLI_VERSION if it is set.
  • Remove the setting TAILWIND_CLI_CONFIG_FILE if it is set.
  • Remove the tailwind.config.js from your project.