django-tailwind-cli

GitHub Workflow Status GitHub Django Versions Python Versions

Tailwind CSS for Django without Node.js. The library downloads the standalone Tailwind CSS CLI and wires it into Django management commands, so there is no npm, no webpack, and no separate build tool to configure. It follows the approach of the Tailwind integration for Phoenix.

What it does

Downloads and manages the Tailwind CLI binary for your platform
Rebuilds CSS on change, running under Django's own auto-reloader
Produces minified production builds containing only the classes you use, and skips work when nothing changed
Includes the CSS via a {% tailwind_css %} template tag
Supports DaisyUI through tailwindcss-cli-extra
Targets Tailwind CSS 4.x

Installation

1. Install the package

# Using pip
pip install django-tailwind-cli

# Using uv
uv add django-tailwind-cli

# Using poetry
poetry add django-tailwind-cli

2. Configure Django settings

Add to your settings.py:

INSTALLED_APPS = [
    # ... your other apps
    "django_tailwind_cli",
]

# Configure static files directory — make sure it exists on disk,
# Django raises an error at startup if it does not.
STATICFILES_DIRS = [BASE_DIR / "assets"]

mkdir -p assets

3. Set up your base template

Create or update your base template (e.g. templates/base.html):

<!DOCTYPE html>
{% load tailwind_cli %}
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Django App</title>
    {% tailwind_css %}
</head>
<body class="bg-gray-50">
    <div class="container mx-auto px-4">
        {% block content %}{% endblock %}
    </div>
</body>
</html>

4. Start developing

# Start Django's dev server with a parallel Tailwind watcher
python manage.py tailwind runserver

# Or run build and watch separately
python manage.py tailwind watch  # In one terminal
python manage.py runserver       # In another terminal

The watcher runs under Django's own auto-reloader, so editing settings.py (e.g. adding a new app) restarts it automatically and picks up the new configuration on the fly. Pass --noreload to opt out.

First run creates a managed <BASE_DIR>/.django_tailwind_cli/ directory for the CLI binary and an auto-generated source.css. The directory is automatically git-ignored — no entry in your project-level .gitignore needed.

python manage.py tailwind setup walks the same ground: it checks each piece in order, stops at the first one that is missing with instructions, and performs the download and first build when they are needed.

Management commands

Command	Purpose	Example
`setup`	Guided first-time setup and checks	`python manage.py tailwind setup`
`build`	Production CSS build	`python manage.py tailwind build`
`watch`	Development file watcher (Django autoreload by default)	`python manage.py tailwind watch`
`runserver`	Django dev server + watcher (forwards any runserver flag)	`python manage.py tailwind runserver`
`config`	Show current configuration	`python manage.py tailwind config`
`troubleshoot`	Debug common issues	`python manage.py tailwind troubleshoot`
`optimize`	Performance tips for build and watch	`python manage.py tailwind optimize`
`download_cli`	Fetch the CLI binary without building	`python manage.py tailwind download_cli`
`remove_cli`	Delete the downloaded CLI binary	`python manage.py tailwind remove_cli`

build takes --force to rebuild regardless of change detection; build and watch both take --verbose for detailed diagnostics.

tailwind runserver is a transparent passthrough: every positional argument and option (apart from --force-default-runserver) is forwarded verbatim to the underlying runserver or runserver_plus. Every flag those commands accept works — including runserver_plus-only ones like --extra-file, --reloader-interval, and --print-sql.

Requirements

Python: 3.10+
Django: 4.2 LTS, 5.2, 6.0, or 6.1
Platform: Windows, macOS, Linux (automatic platform detection)

Configuration

Beyond adding the app to INSTALLED_APPS, STATICFILES_DIRS is the only setting you have to configure. Everything below is optional; see the settings reference for the full list.

# Pin a specific Tailwind version instead of tracking the latest release
TAILWIND_CLI_VERSION = "4.1.3"

# Custom CSS paths
TAILWIND_CLI_SRC_CSS = "src/styles/main.css"
TAILWIND_CLI_DIST_CSS = "css/app.css"

# Enable DaisyUI
TAILWIND_CLI_USE_DAISY_UI = True

# Use an already-installed Tailwind binary (e.g. `brew install tailwindcss`)
TAILWIND_CLI_USE_SYSTEM_BINARY = True

# Auto-inject @source directives for editable-installed external apps (opt-in)
TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS = True

For production, pin the version and provide the binary yourself rather than downloading it during a build:

TAILWIND_CLI_VERSION = "4.1.3"
TAILWIND_CLI_AUTOMATIC_DOWNLOAD = False
TAILWIND_CLI_PATH = "/usr/local/bin/tailwindcss"  # where your binary actually is
TAILWIND_CLI_DIST_CSS = "css/tailwind.min.css"

DaisyUI

Setting TAILWIND_CLI_USE_DAISY_UI = True switches to the DaisyUI-enabled CLI build, which makes its component classes available:

<button class="btn btn-primary">Primary Button</button>
<div class="card bg-base-100 shadow-xl">
    <div class="card-body">
        <h2 class="card-title">Card Title</h2>
        <p>Card content goes here.</p>
    </div>
</div>

Troubleshooting

CSS not updating?

python manage.py tailwind build --force
python manage.py tailwind troubleshoot

Configuration problems?

python manage.py tailwind config
python manage.py tailwind setup

Classes from some templates are missing?

Make sure every template directory is covered by an @source directive in your Tailwind CSS input file — Tailwind CSS 4.x discovers templates exclusively through those directives. Declaring them explicitly also keeps builds fast, because Tailwind only scans what you list.

Documentation and related projects

Full documentation
Tailwind CSS documentation
DaisyUI components
tailwindcss-cli-extra — the DaisyUI-enabled CLI build
Django Extensions — provides runserver_plus
Tailwind CSS IntelliSense — VS Code extension
Django Commons

Contributing

Contributions are welcome. CONTRIBUTING.md covers the development setup (mise provisions Python, uv, and pre-commit), how to run the tests, and what a pull request should look like. Please read the short section at the top of it before opening an issue or a pull request — it explains what makes one easy to act on.

License

This software is licensed under MIT license.

Metadata

Release files for django-tailwind-cli 4.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-tailwind-cli 4.8.0
File	Size	Uploaded
django_tailwind_cli-4.8.0.tar.gz	166.0 kB	Aug 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for django-tailwind-cli 4.8.0
File	Interpreter	ABI	Platform	Reset
django_tailwind_cli-4.8.0-py3-none-any.whl 54.1 kB Aug 30, 2026	Python 3	none	any	Details

Total release size: 220.1 kB

Release files / django_tailwind_cli-4.8.0.tar.gz

Download URL	django_tailwind_cli-4.8.0.tar.gz
Size	166.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`d97b465272a67db96a86532a20658b72f3c31e64b7f788f77ec2ab059c3deb64`
BLAKE2b-256 checksum How to use checksums	`f1145e161990f173ec8f4ec906d2f6055cb20376e5d4ee2b84cb18393b3b976f`
Upload date	Aug 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/django-commons/django-tailwind-cli
Publishing commit: github.com/django-commons/django-tailwind-cli/tree/ee81019978786395c5fd73fb8f99deb1dce2188b

Workflow

Publishing configuration: github.com/django-commons/django-tailwind-cli/blob/ee81019978786395c5fd73fb8f99deb1dce2188b/.github/workflows/release.yml
Publishing logs: github.com/django-commons/django-tailwind-cli/actions/runs/33307917002/attempts/1

Artifact

Subject: django_tailwind_cli-4.8.0.tar.gz
SHA-256 checksum: d97b465272a67db96a86532a20658b72f3c31e64b7f788f77ec2ab059c3deb64 Verifying attestations

Release files / django_tailwind_cli-4.8.0-py3-none-any.whl

Download URL	django_tailwind_cli-4.8.0-py3-none-any.whl
Size	54.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`04adb4cecd1c2165e517e05f756e055bf1004159f52f00808a459a2e7cf580fa`
BLAKE2b-256 checksum How to use checksums	`07fd454bad110a4276e709dfeeff14b00af653d6eb426aba21444f480e954dda`
Upload date	Aug 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/django-commons/django-tailwind-cli
Publishing commit: github.com/django-commons/django-tailwind-cli/tree/ee81019978786395c5fd73fb8f99deb1dce2188b

Workflow

Publishing configuration: github.com/django-commons/django-tailwind-cli/blob/ee81019978786395c5fd73fb8f99deb1dce2188b/.github/workflows/release.yml
Publishing logs: github.com/django-commons/django-tailwind-cli/actions/runs/33307917002/attempts/1

Artifact

Subject: django_tailwind_cli-4.8.0-py3-none-any.whl
SHA-256 checksum: 04adb4cecd1c2165e517e05f756e055bf1004159f52f00808a459a2e7cf580fa Verifying attestations