Getting started
Installation
Section titled “Installation”djLint is on PyPI, where it needs Python 3.11 or newer, and on npm, which brings its own Python. In a Python project, add it with uv or pip. In a JavaScript project, such as an Angular app, an Eleventy site or a Shopify theme, add it with npm.
With uv, add it to your project as a development dependency:
uv add --dev djlintOr install it as a standalone tool:
uv tool install djlintpip install djlintThe npm package comes with its own Python, so all it needs is Node.js 16.9 or newer. It has builds for Linux on x64, Arm64, ppc64le, s390x and riscv64, macOS on x64 and Arm64, and Windows on x64, x86 and Arm64. On Linux with musl, such as Alpine, it runs on x64 and Arm64. Add it to your project as a development dependency:
npm i -D djlintOr install it globally:
npm i -g djlintWith pipx:
pipx install djlintWith the community-maintained Homebrew formula on macOS or Linux:
brew install djlintTo run djLint in your editor or on every commit, see Integrations and pre-commit.
First run
Section titled “First run”Point djLint at the folder with your templates and set --profile to your template language. The profile decides which linter rules run and how the template syntax is formatted. For a Django project:
Lint the templates (linting is the default mode, so --lint can be left out):
djlint templates --lint --profile=djangoSee what reformatting would change. With --check, djLint prints a diff and leaves the files alone:
djlint templates --check --profile=djangoReformat the files in place:
djlint templates --reformat --profile=djangoThe profile option lists every profile. Each template language also has its own page, for example Django, Jinja or Handlebars, which shows how to set the profile in a config file so you don’t have to pass it every time.
If you added djLint to a project with uv add --dev, it lives in the project’s environment: put uv run in front of the commands, as in uv run djlint templates --lint --profile=django. With npm i -D, put npx in front of them instead, as in npx djlint templates --lint --profile=django.
Using path vs stdin
Section titled “Using path vs stdin”djLint works with a path or stdin.
Running with a path:
djlint /path/to/templates --lintOr a specific file:
djlint /path/to/this.mustache --lintOr with stdin:
echo "<div></div>" | djlint -Stdin can also be used to reformat code. The output will be only the formatted code without messages.
echo "<div></div>" | djlint - --reformatOutput:
<div></div>When reading from stdin, djLint has no real path to match against per-file-ignores or to show in messages, so it uses - by default. Pass --stdin-filename to tell djLint the real path of the piped content, for example when an editor integration pipes a file’s contents in on save.
echo "<div></div>" | djlint - --stdin-filename templates/index.htmlExit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 |
Everything djLint was asked to check is clean, or every file it found was skipped by your configuration. |
1 |
djLint found linting errors, or files that need reformatting. --warn reports these as warnings and exits 0 instead. |
2 |
djLint did not check what you asked it to: the paths matched no files, a file couldn’t be read (not UTF-8, or no permission), the command line or config was invalid, or djLint failed. |
Only code 1 means djLint looked at your templates and did not like what it found, so a pipeline can tell a failing check from a run that checked nothing, such as one with a wrong path or an --extension that no longer matches.
Files djLint found and then skipped on purpose, through exclude, extend_exclude, use_gitignore or require_pragma, are not an error, which is what lets exclude work under pre-commit. If a path with no templates is normal for your pipeline, turn code 2 off with allow_empty_input:
djlint /path/to/templates --lint --allow-empty-inputCLI usage
Section titled “CLI usage”Usage: djlint [OPTIONS] SRC ...
djLint · HTML template linter and formatter.
Modes: --lint Lint the files. This is the default when neither --reformat nor --check is given. --reformat Format the files in place. --check Show what formatting would change, without changing the files. --lsp Run as a language server over stdio, for editors.
Files: -e, --extension EXT Extension of the files to look for in folders. [default: html] --exclude PATHS Regexes of the paths to skip, comma-separated, in place of the default list. --extend-exclude PATHS Regexes of the paths to skip on top of the exclude list, comma-separated. --use-gitignore Also skip the paths that the .gitignore in the project root lists. --require-pragma Only format or lint files whose first line is a djlint:on comment. --stdin-filename PATH Path that stands for stdin in messages, excludes and per-file ignores. [default: -] --allow-empty-input Exit with 0 instead of 2 when the given paths match no files.
Configuration: --profile NAME Template language: html, django, jinja, nunjucks, handlebars, liquid, golang, angular, tera, askama, mako or all. It decides which linter rules run and how template syntax is formatted. Without one, formatting follows all and the linter runs the rules of html. --configuration FILE Global config file: a pyproject.toml, djlint.toml or .djlintrc. The project's own config file wins where both set an option. --prefer-configuration Let the --configuration file win over the project's own config file.
Linter: -i, --ignore CODES Linter codes to skip, comma-separated, for example H014,H017. --include CODES Linter codes to turn on, comma-separated, for example H017. Works for rules that are off by default and for rules the profile leaves out. --per-file-ignores <PATTERN CODES>... Skip linter codes in the files whose path matches a regex. Can be repeated. --rules FILE Custom linter rules, in the .djlint_rules.yaml format.
Output: --quiet Do not print diffs, the progress bar or the summary. --warn Exit with 0 instead of 1 when there are lint errors or files to reformat. --statistics After linting, print how many times each code was found. --linter-output-format FORMAT Layout of each lint message, from {filename}, {line}, {end}, {code}, {message} and {match}. [default: {code} {line} {message} {match}] --github-output / --no-github-output Print results as GitHub Actions annotations. On by default inside GitHub Actions. --sarif Print findings as a SARIF 2.1.0 JSON document, for GitHub code scanning and other tools.
Layout: --indent N Spaces per indent level. [default: 4, or indent_size from .editorconfig] --max-line-length N Join tags onto one line only when the line fits within this length. [default: 120, or max_line_length from .editorconfig] --max-attribute-length N Spread a tag's attributes over lines once they are longer than this. [default: 70] --single-attribute-per-line When an opening tag wraps, put each attribute on its own line. --line-break-after-multiline-tag When a tag's attributes are spread over lines, start its content on a new line. --no-indent-inner-html Do not indent <head> and <body> inside <html>. --keep-br-inline Keep <br> on the line of the text it breaks. --custom-blocks TAGS Names of the custom template blocks to indent, comma-separated, for example toc. --custom-html TAGS Names of the custom HTML tags to indent, comma-separated, for example mjml. --ignore-blocks TAGS Template blocks that do not indent their contents, comma-separated. --blank-line-after-tag TAGS Template tags to follow with a blank line, comma-separated, for example load,extends. --blank-line-before-tag TAGS Template tags to precede with a blank line, comma-separated, for example load,extends. --max-blank-lines N Keep at most this many blank lines in a row. Has no effect with --preserve-blank-lines. [default: 0] --preserve-blank-lines Keep blank lines where possible. --preserve-leading-space Keep the leading spaces of text lines where possible. --no-line-after-yaml Do not add a blank line after YAML front matter.
Rewrites: --close-void-tags Close void tags with a slash, so <img> becomes <img />. --ignore-case Do not fix the case of known HTML tags. --sort-attributes Sort attributes by name, with id first and class second. --sort-load-tags Sort the libraries in {% load %} tags and drop repeated ones. --name-endblocks Name the block in its {% endblock %} when the block spans lines. --quote-style [double|single] Quotes for strings inside template tags. [default: double] --no-entity-formatting Do not rewrite entity references such as © as the characters they name. --no-function-formatting Do not format the arguments of function calls inside {{ }}. --no-set-formatting Do not format the contents of {% set %} tags. --preserve-class-newlines Keep the line breaks in class attributes written across lines. --format-attribute-template-tags Format template syntax inside tag attributes.
CSS and JavaScript: --format-css Also format the contents of <style> tags, with css-beautify. --indent-css N Indent width inside <style> tags, for --format-css. [default: 4] --format-js Also format JavaScript and JSON in <script> tags, with js-beautify. --indent-js N Indent width inside <script> tags, for --format-js. [default: 4] --format-attribute-js-json Also format JavaScript and JSON in attributes such as onclick and x-data. --format-attribute-js-json-pattern REGEX Regex for the names of the attributes to format as JavaScript or JSON. [default: on* event handlers and Alpine, Vue, Angular and Aurelia bindings] --format-attribute-js-json-min-props N Format an object only when it has at least this many properties. [default: 2]
Other: --version Show the version and exit. -h, --help Show this message and exit.