Usage

Do I have to install the Tailwind CLI?

No. The management commands of this library handle the download and installation of the Tailwind CLI. You don’t have to deal with this. But you can configure the installation location and the version of the CLI you want to use. Take a look at the settings section.

Do I have to create my own source.css for Tailwind 4.x?

No. The management commands also take care of this step. If no source CSS file is present yet, one with sane defaults is created at <BASE_DIR>/.django_tailwind_cli/source.css. You can point at a hand-written file instead by setting TAILWIND_CLI_SRC_CSS in your Django settings — the library leaves your file alone in that case.

The generated file is managed: every build regenerates it, so edits you make there are replaced. The command says so before it overwrites them and keeps your version as source.css.bak next to it. Custom CSS belongs in a file of your own, pointed at by TAILWIND_CLI_SRC_CSS.

Is .django_tailwind_cli/ safe to commit?

No, and you don’t have to do anything. On first use the library writes a .gitignore containing * into the managed directory, so the downloaded CLI binary and the auto-generated source.css are silently ignored by Git — no entry in your project-level .gitignore needed.

The compiled stylesheet is a different matter. It is written into your static files directory, which the library does not manage, so add it yourself — assets/css/tailwind.css for the default configuration.

Management commands

build

Run python manage.py tailwind build to create an optimized production build of the stylesheet. Afterwards you are ready to deploy. Make sure this command runs before python manage.py collectstatic in your build process — with a manifest storage backend, the wrong order fails at render time rather than at build time.

watch

Run python manage.py tailwind watch to start a Tailwind watcher process on its own — useful if you prefer to run your debug server in a separate shell or use a workflow other than runserver / runserver_plus.

By default the watch command runs under Django’s own auto-reloader (the same one runserver uses). Whenever you change a Python file — including settings.py — the watcher restarts its Python process, regenerates the default source CSS file (picking up freshly added INSTALLED_APPS), and respawns the Tailwind CLI subprocess. This pairs nicely with TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS: adding an editable-installed app and updating INSTALLED_APPS is enough — no manual restart needed.

Pass --noreload if you want a single-process watch loop (e.g. in CI or when debugging the watcher itself):

python manage.py tailwind watch --noreload

runserver

Run python manage.py tailwind runserver to start the Django debug server in parallel to a tailwind watcher process. If django-extensions plus werkzeug are installed, runserver_plus is used automatically; otherwise the vanilla runserver command runs.

Both halves are started as python manage.py … from BASE_DIR, so this command needs a manage.py there and refuses to start without one. Projects that keep it elsewhere run the two halves separately: tailwind watch in one terminal, manage.py runserver in another.

This command is a transparent passthrough wrapper: every positional argument and option other than the tailwind-specific --force-default-runserver is forwarded verbatim to the underlying server command. That includes flags the wrapper itself does not know about (e.g. runserver_plus’s --extra-file, --reloader-interval, --browser, --exclude-pattern, …).

For the exhaustive list of forwarded flags, run:

python manage.py runserver --help
python manage.py runserver_plus --help   # with django-extensions

Examples:

# Default port (8000)
python manage.py tailwind runserver

# Custom port
python manage.py tailwind runserver 8080

# Forward arbitrary runserver / runserver_plus flags
python manage.py tailwind runserver 0.0.0.0:8000 --noreload
python manage.py tailwind runserver --print-sql --ipdb

# Pin to vanilla runserver even with django-extensions installed
python manage.py tailwind runserver --force-default-runserver

download_cli

Run python manage.py tailwind download_cli to download the CLI without building anything. It fetches the correct version for your platform and stores it in the path configured by the TAILWIND_CLI_PATH setting.

config

Run python manage.py tailwind config to show current Tailwind CSS configuration. This command displays the current configuration settings and their values, helping you understand how django-tailwind-cli is configured in your project.

The command shows:

  • All configuration paths (CLI, CSS input/output)

  • Version information

  • Django settings values

  • File existence status

  • Platform information

setup

Run python manage.py tailwind setup for a guided first-time setup. The command walks the steps in order, stops at the first blocker with instructions, and performs the CLI download and first build when they are missing. It does not prompt for anything, so it is safe to run repeatedly.

The guide covers:

  1. Installation verification

  2. Django settings configuration

  3. CLI binary download

  4. First CSS build

  5. Template integration

  6. Development workflow

Use it for a first-time setup, or when you want to check how the pieces fit together.

troubleshoot

Run python manage.py tailwind troubleshoot to access the troubleshooting guide for common issues. This command provides solutions for the most common issues encountered when using django-tailwind-cli, with step-by-step debugging guidance.

Common issues covered:

  • CSS not updating in browser

  • Build failures and errors

  • Missing or incorrect configuration

  • Permission and download issues

  • Template integration problems

optimize

Run python manage.py tailwind optimize to view performance optimization tips and best practices. This command provides detailed guidance on optimizing your Tailwind CSS build performance and development workflow for the best possible experience.

Areas covered:

  • Build performance optimization

  • File watching efficiency

  • Template scanning optimization

  • Production deployment best practices

  • Development workflow improvements

  • Common performance pitfalls

remove_cli

Run python manage.py tailwind remove_cli to remove the installed CLI binary. This only works with the managed download; system binaries (TAILWIND_CLI_USE_SYSTEM_BINARY = True) are refused.

Use with Docker Compose

When used in the watch mode, the Tailwind CLI requires a TTY-enabled environment to function correctly. In a Docker Compose setup, ensure that the container executing the Tailwind style rebuild command (either python manage.py tailwind runserver or python manage.py tailwind watch, as noted above) is configured with the tty: true setting in your docker-compose.yml.

web:
  command: python manage.py tailwind runserver
  tty: true

# or

tailwind-sidecar:
  command: python manage.py tailwind watch
  tty: true

Use with WhiteNoise

WhiteNoise works with the defaults of this library and needs no extra configuration. See Use with WhiteNoise for a sample configuration and the traps around collectstatic.