Django Tailwind

4.4.2 · active · verified Thu Apr 16

The django-tailwind library integrates the Tailwind CSS framework seamlessly into Django projects. It provides management commands to install, build, and serve Tailwind CSS, streamlining frontend development within a Django context. It is actively maintained with frequent releases, currently at version 4.4.2.

Common errors

```
command 'npm' not found
```
cause Node.js or npm is not installed, or not in your system's PATH.

fix Install Node.js and npm from their official website (nodejs.org) for your operating system. Verify installation with `node -v` and `npm -v`.
```
Error: Cannot find module 'tailwindcss'
```
cause Tailwind CSS itself has not been correctly installed within the project's Tailwind app directory by npm.

fix Ensure `TAILWIND_APP_NAME` is set in `settings.py` and then run `python manage.py tailwind install` to install `tailwindcss` and other npm dependencies into your project.
```
Unknown command: 'tailwind'
```
cause `django_tailwind` is not included in your `INSTALLED_APPS` in `settings.py`.

fix Add `'django_tailwind'` to your `INSTALLED_APPS` list in `settings.py`.
```
Staticfiles manifest entry for 'css/tailwind.css' not found
```
cause The Tailwind CSS file was not generated or collected into your static files during production deployment.

fix Ensure you run `python manage.py tailwind build` to compile the CSS for production, and then `python manage.py collectstatic` to gather all static files, including the generated Tailwind CSS.

Warnings

breaking Version 4.0 introduced several breaking changes including renaming `TAILWIND_CSS_PATH` to `TAILWIND_INPUT_CSS_PATH`, removing `TAILWIND_POSTCSS_OPTIONS` and `TAILWIND_NPM_PATH`, and requiring `TAILWIND_APP_NAME` to be set before `tailwind install`.
Fix: Review your `settings.py` for renamed variables. Ensure `TAILWIND_APP_NAME` is configured before running `python manage.py tailwind install`.
gotcha django-tailwind requires Node.js and npm to be installed on your system for the Tailwind CLI to function correctly. These are not Python dependencies and must be installed separately.
Fix: Install Node.js and npm for your operating system. Verify installation by running `node -v` and `npm -v` in your terminal.
gotcha The `TAILWIND_APP_NAME` setting must be defined in your `settings.py` BEFORE running `python manage.py tailwind install`. Failure to do so can lead to an incomplete setup or errors during installation.
Fix: Ensure `TAILWIND_APP_NAME = 'your_app_name'` is correctly configured in `settings.py` and that `your_app_name` is also in `INSTALLED_APPS` before executing `python manage.py tailwind install`.
gotcha There's a distinction between `python manage.py tailwind start` (for development with hot-reloading) and `python manage.py tailwind build` (for production static file generation). Using `start` in production will not generate optimized static assets.
Fix: Use `python manage.py tailwind start` during development. For production deployment, ensure you run `python manage.py tailwind build` to compile your CSS, followed by `python manage.py collectstatic` to gather the output.

Install

pip install django-tailwind Install package

Imports

django_tailwind
```
INSTALLED_APPS = ['django_tailwind', ...]
```
Required in settings.py for management commands and template tags.
TAILWIND_APP_NAME
```
TAILWIND_APP_NAME = 'theme'
```
Required in settings.py to specify the Django app hosting Tailwind's static files.
tailwind_tags
```
{% load tailwind_tags %}
```
Required in Django templates to use Tailwind's template tags.
tailwind_css
```
{% tailwind_css %}
```
Required in Django templates (typically base.html) to link the generated Tailwind CSS.

Quickstart

To quickly get started, add `django_tailwind` and your designated Tailwind app (e.g., 'theme') to `INSTALLED_APPS`, define `TAILWIND_APP_NAME`, include `django_tailwind.urls` in your project's `urls.py`, and use `{% tailwind_css %}` in your base template. Then, run `python manage.py tailwind install` to set up Node.js dependencies and `python manage.py tailwind start` for development.

# settings.py
INSTALLED_APPS = [
    # ... your other apps
    'django_tailwind',
    'theme', # Your Tailwind app name
]

TAILWIND_APP_NAME = 'theme'

# urls.py (your project's main urls.py)
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('django_tailwind.urls')),
    # ... your other url patterns
]

# Your Tailwind app (e.g., 'theme/apps.py')
# Make sure to define your Tailwind app as a Django app
# For example:
# from django.apps import AppConfig
# class ThemeConfig(AppConfig):
#     default_auto_field = 'django.db.models.BigAutoField'
#     name = 'theme'

# In your base template (e.g., templates/base.html)
# Make sure to create a templates directory in your 'theme' app
# and an input.css in 'theme/static_src/input.css'
# {% load tailwind_tags %}
# <head>
#     <title>My Django Tailwind App</title>
#     {% tailwind_css %}
# </head>
# <body>
#     <h1 class="text-3xl font-bold underline">Hello Tailwind!</h1>
# </body>

# Terminal commands
# python manage.py tailwind install
# python manage.py tailwind start
# (Open browser to your Django app, check console for Tailwind CSS build output)

view raw JSON →