Django: a README that is a reading order, a version field that is empty, and a classifier that says Pre-Alpha

The README is a reading order, and install.txt is the first entry

There is no install command in the Django README. What it gives instead is a sequence: read docs/intro/install.txt for installation instructions, then work through the tutorials in order, docs/intro/tutorial01.txt, docs/intro/tutorial02.txt, and the rest, then docs/howto/deployment/index.txt if you are setting up a real server, then the topical guides in docs/topics, the HOWTOs in docs/howto for specific problems, and the reference in docs/ref for details.

Consequence for the reader: the file most people meet first tells you nothing about what is in the framework. The description on the repository page is where routing, templates, forms, authentication, an ORM, and an administrative interface are actually named, and everything else is behind a pointer to a documentation tree.

One more file is in that list and is easy to miss: docs/README carries the instructions for building an HTML version of the documentation. If you want the docs offline, that is the file, not a download link.

Three runtime dependencies, and tzdata exists only on Windows

pyproject.toml lists three dependencies. asgiref is required at 3.12.1 or newer, sqlparse at 0.5.0 or newer, and tzdata carries a marker of sys_platform == 'win32', so it is pulled in on Windows and nowhere else.

The classifier list is more specific than the requirement. It names Python 3.12, 3.13, and 3.14, and adds Programming Language :: Python :: Free Threading :: 2 - Beta, which is the project's own statement about how the free-threaded build should be read.

Consequence for the reader: the floor is not negotiable, since requires-python is >= 3.12 and there is no lower branch. And on Linux or macOS nothing installs a timezone database for you, so a deployment that assumes Django ships one is relying on the operating system instead of on this package.

The version field is dynamic, and the trove classifier says Pre-Alpha

Two fields in the project metadata are worth reading before you trust the rest. The first is dynamic = ["version"], which means pyproject.toml deliberately contains no version string. The second is the classifier Development Status :: 2 - Pre-Alpha, sitting in the same list as Environment :: Web Environment and Framework :: Django.

[project]
name = "Django"
dynamic = ["version"]
requires-python = ">= 3.12"

Consequence for the reader: a tool that reads package metadata to decide maturity sees Pre-Alpha, and a tool that pins a version cannot read one from this file at all. Neither is a statement about the framework's behaviour, and both will mislead an automated pipeline that takes trove classifiers at face value. If your process gates dependencies on declared maturity, Django needs an exception.

argon2 and bcrypt are optional extras, so the password hasher is your decision

The optional-dependencies table has exactly two entries, argon2 pulling in argon2-cffi at 23.1.0 or newer, and bcrypt pulling in bcrypt at 4.1.1 or newer. Neither is in the required list.

Consequence for the reader: the hasher you choose at settings time is not present on a default install, and the failure arrives as an import error inside the authentication path rather than as a package resolution problem at install time. A project that selects Argon2 and forgets the extra looks identical to a project with a broken password backend until a user tries to log in.

One console script, django-admin, and no other entry point

The scripts table declares a single executable:

[project.scripts]
django-admin = "django.core.management:execute_from_command_line"

There is no django binary and no second alias. Consequence for the reader: every management task, including the ones a newcomer expects to be their own command, arrives through the one entry point that dispatches into django.core.management. If you are writing a Docker image or a systemd unit, the command you type is django-admin, and the arguments after it are what the management layer defines rather than anything this file documents.

The package ships three licence files, not one

license is BSD-3-Clause, and license-files names three paths: LICENSE, LICENSE.python, and AUTHORS. The last of those is not a licence text at all, it is the file that records who wrote the code.

Consequence for the reader: a compliance check that looks for a single LICENSE file and stops there will read the first file and miss that this distribution also carries a separate licence for the Python standard library vendored inside it, plus an authors list. Anyone redistributing a Django dependency has to distribute all three, and a script that copies only LICENSE produces an incomplete notice.

No GitHub releases, so the changelog is a file under docs

The repository publishes no GitHub releases. The release notes are a documentation path instead, registered in the project URLs as Release notes pointing at the stable documentation site, alongside Homepage, Documentation, and a Funding entry for the Django Software Foundation.

Consequence for the reader: you cannot read the project's own change history from the repository page, and a GitHub Releases-based upgrade check written against this project finds nothing to check. You end up reading the release notes page and matching it against your installed version yourself, which is a manual step most dependency bots will not do for you.

The last push to main was on 2026-09-29, so the branch is current even though the tag history is not visible from here.

Contributing runs a Python tox setup and a Node grunt and QUnit setup

The repository carries both toolchains side by side. On the Python side there is tox.ini, a .flake8 file, and a .pre-commit-config.yaml, and the README sends contributors to docs/internals/contributing/writing-code/unit-tests.txt for the unit test instructions. On the JavaScript side there is a package.json, a Gruntfile.js, a js_tests/ directory, and a biome.json.

The JavaScript half is where the structure shows:

"test": "grunt test --verbose",
"biome": "biome check"

The devDependencies behind that script are grunt, grunt-cli, grunt-contrib-qunit, and qunit, so the browser-facing JavaScript in this project is tested through QUnit driven by Grunt, not by a JavaScript framework's own runner.

Consequence for the reader: a patch that touches only Python still sits in a repository whose JavaScript checks are wired to a Node toolchain, and package.json declares npm >= 1.3.0 as its engine, which tells you the JavaScript tooling predates modern Node version floors. The README points to the contributing guide for the full procedure rather than describing it here.

Editorial conclusion

Adopt Django if you want the admin interface, the ORM, and the authentication that come in the box and do not mind the opinionated structure, and read docs/intro/install.txt rather than the README when you set it up. Do not use the README as a feature list: it names no components, no commands, and no version, and the framework's own site is where those live. Before you pin anything, check three things: that your interpreter is 3.12 or newer, which the requires-python field refuses to go below, that you have installed the argon2 or bcrypt extra if you plan to use either hasher, and which release line you are on, since the repository publishes no GitHub releases and the release notes are a file under docs.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository