Install & Compatibility
Where this runs
tested against v1.44.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.536s · 29.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.2s · import 0.494s · 31MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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")
djlint --version
Debug
Known issues
breakingPython 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.fixUpgrade Python to 3.9 or higher.
affects: >=1.35.3
gotchaReformatting may duplicate file contents or incorrectly handle non-ASCII characters on Windows with specific older versions.fixEnsure 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.
affects: v1.1.1 to v1.12.1
gotchaConfiguration files (e.g., `pyproject.toml`, `.djlintrc`) might be ignored if placed in the project root on some older Python versions.fixUpdate djLint to version 1.19.2 or higher to ensure configuration files are properly recognized.
affects: <1.19.2
gotchaReformatting does not work reliably with long JSON/HTML content embedded directly into attribute data within templates.fixAvoid 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.
affects: All versions
gotchaWhen `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.fixUse spaceless template tags (e.g., `{% if condition -%}class2{%- endif %}`) around conditional attributes to control whitespace, as recommended in best practices. affects: All versions with `format_attribute_template_tags` enabled.
Errors
Common errors & fixes
djlint: command not found
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.
fixInstall `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.
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.
fixYou 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.
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.
fixSelect 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.
Upgrade
Version history
1.44.2latest on PyPI · released Aug 8, 2026
Audit
Dependencies
pythonrequireddjLint is built with Python and requires Python 3.9 or higher.