Tooling

The build, test, and lint tools used by the Django project. All of them are configured at the repo root or in pyproject.toml.

tox

tox.ini defines environments for the test matrix and ancillary tasks:

Env	Purpose
py3	Test suite on the system Python
py312 / py313 / py314	Test suite on a specific Python version
postgres	Test suite with PostgreSQL test config
mysql	Test suite with MySQL test config
oracle	Test suite with Oracle test config
black	black --check
blacken-docs	Format code blocks inside .rst files
flake8	flake8 lint
isort	isort --check-only
docs	Sphinx HTML build (treats warnings as errors)
lint-docs	The custom prose linter at docs/lint.py
zizmor	Lint for .github/workflows/

The [testenv] block sets changedir = tests and runs runtests.py {posargs}, so tox -- queries -k subquery works.

pre-commit

.pre-commit-config.yaml runs on every commit (after pre-commit install). The hooks:

• black (tool.black.target-version = py312).
• isort (profile = black, first-party = django).
• flake8 (config in .flake8).
• pyupgrade --py312-plus.
• eslint for the JavaScript test sources in js_tests/ and admin assets.
• prettier for some JS/CSS files (config: biome.json is used for the newer parts).
• blacken-docs for code blocks inside .rst.

Run all hooks against the whole tree:

pre-commit run --all-files

flake8

.flake8 configures:

• Max line length 88 (matches black).
• Excludes for vendored or generated files.
• A few custom ignores for legacy code that can't be easily fixed without churn.

black + isort

Configured in pyproject.toml:

[tool.black]
target-version = ["py312"]
force-exclude = "tests/test_runner_apps/tagged/tests_syntax_error.py"

[tool.isort]
profile = "black"
default_section = "THIRDPARTY"
known_first_party = "django"

The exclude is for an intentionally syntax-broken test file.

Sphinx (docs build)

The docs are built with Sphinx. Config:

• docs/conf.py — Sphinx settings, custom roles (e.g., :setting:, :ttag:, :tfilter:).
• docs/_ext/ — Custom Sphinx extensions for Django-specific cross-references.
• docs/_theme/ — The djangodocs theme.
• docs/Makefile and docs/make.bat — make html, make linkcheck, etc.
• docs/requirements.txt — Sphinx + extensions pinned for reproducible builds.

The build runs in tox -e docs with -W (warnings as errors) so a missing cross-reference fails CI.

lint-docs

docs/lint.py is a custom prose linter that catches Django-specific style issues — unbalanced backticks, :setting: references that point at non-existent settings, etc. It's run as tox -e lint-docs and as a CI step.

zizmor

zizmor.yml configures the workflow linter that checks .github/workflows/ for security issues (untrusted inputs, commit pinning, etc.). Run via tox -e zizmor.

Biome / ESLint

biome.json configures Biome for JS/CSS in newer assets. Older assets in django/contrib/admin/static/ and js_tests/ use ESLint. The pre-commit config wires both in.

Gruntfile.js

Gruntfile.js lives at the repo root and orchestrates the JavaScript test runner (qunit) for js_tests/. CI invokes it via npm test.

Pre-commit configuration map

Tool	Config file	Invocation
black	pyproject.toml [tool.black]	tox -e black, pre-commit
isort	pyproject.toml [tool.isort]	tox -e isort, pre-commit
flake8	.flake8	tox -e flake8, pre-commit
pre-commit	.pre-commit-config.yaml	pre-commit run --all-files
Sphinx	docs/conf.py	tox -e docs
docs lint	docs/lint.py	tox -e lint-docs
zizmor	zizmor.yml	tox -e zizmor
Biome	biome.json	pre-commit, npx biome check

CI

.github/workflows/ contains the GitHub Actions workflows. The workflows run the full matrix (Python × backend) on PRs. They mirror the tox envs above; if your PR passes tox locally on the backend you care about, CI is mostly a formality.