djLint

Common errors

• djlint: command not found

  cause The `djlint` executable is not in your system's PATH, usually because it wasn't installed or the Python environment where it was installed is not active.
  fix Install `djlint` using pip: `pip install djlint`. If it's already installed, ensure your Python environment is activated or that Python's script directory is in your system's PATH.

• H030: Consider adding a meta description.

  cause This is a linting suggestion from `djlint`'s HTML best practices rules (specifically for SEO), not an error preventing execution. Similar warnings like 'H031: Consider adding meta keywords.' also appear.
  fix You can either add the suggested `<meta>` tags to your HTML or ignore the rules via the command line (`djlint your_file.html --ignore H030,H031`) or in a configuration file (`ignore = ["H030", "H031"]` in `djlint.toml`).

• djLint is not installed for the current active Python interpreter.

  cause This error typically occurs when using the `djlint` VS Code extension, indicating that `djlint` is not found in the currently selected Python interpreter's environment within VS Code.
  fix Select the correct Python interpreter in VS Code that has `djlint` installed, or install `djlint` into the active virtual environment using `pip install -U djlint`. Alternatively, configure the VS Code extension settings (`djlint.useVenv` and `djlint.pythonPath`) to point to a globally installed `djlint` or specific Python executable.

Warnings

• breaking Python 3.8 support was dropped in version 1.35.3. Users on Python 3.8 or older will need to upgrade their Python environment to use newer versions of djLint.
  Fix: Upgrade Python to 3.9 or higher.
• gotcha Reformatting may duplicate file contents or incorrectly handle non-ASCII characters on Windows with specific older versions.
  Fix: Ensure djLint is updated to version 1.12.2 or higher to resolve duplication issues, and 1.1.1 or higher for non-ASCII character handling on Windows.
• gotcha Configuration files (e.g., `pyproject.toml`, `.djlintrc`) might be ignored if placed in the project root on some older Python versions.
  Fix: Update djLint to version 1.19.2 or higher to ensure configuration files are properly recognized.
• gotcha Reformatting does not work reliably with long JSON/HTML content embedded directly into attribute data within templates.
  Fix: Avoid embedding excessively long JSON or complex HTML structures directly into attributes if reformatting by djLint is critical for those sections. Consider externalizing such data or using JavaScript for rendering complex structures.
• gotcha When `format_attribute_template_tags` is enabled (for Jinja/Nunjucks), conditional attributes without spaceless tags (e.g., `{% if condition %}` instead of `{% if condition -%}`) can lead to unwanted whitespace after formatting, potentially breaking rendering or styling.
  Fix: Use spaceless template tags (e.g., `{% if condition -%}class2{%- endif %}`) around conditional attributes to control whitespace, as recommended in best practices.

Install

• pip install djlint Install from PyPI

Imports

• Config

  from djlint.settings import Config

  Used for programmatic configuration, typically within custom linter rules.
• get_line

  from djlint.lint import get_line

  Helper function for custom linter rules to get line numbers from character positions.

Quickstart

This quickstart demonstrates how to use `djlint` from the command line within a Python script. It creates a sample HTML file, then runs `djlint` to lint and reformat it. The primary interaction with `djlint` is via its CLI.

import subprocess
import os

# Create a dummy HTML file for demonstration
with open("test_template.html", "w") as f:
    f.write("""
<div    class="my-class" >
    <h1>  Hello, {{ name }}! </h1>
</div>
    """)

print("--- Original File ---")
with open("test_template.html", "r") as f:
    print(f.read())

# Run djlint to check for linting issues
print("\n--- Linting Check ---")
lint_result = subprocess.run(["djlint", "test_template.html", "--lint"], capture_output=True, text=True)
print(lint_result.stdout)
if lint_result.stderr:
    print(lint_result.stderr)

# Run djlint to reformat the file
print("\n--- Reformatting File ---")
reformat_result = subprocess.run(["djlint", "test_template.html", "--reformat"], capture_output=True, text=True)
print(reformat_result.stdout) # Should be empty if reformat is applied directly to file
if reformat_result.stderr:
    print(reformat_result.stderr)

print("\n--- Formatted File ---")
with open("test_template.html", "r") as f:
    print(f.read())

# Clean up the dummy file
os.remove("test_template.html")