Django 6.1.x

Django 6.1 is largely about query efficiency and configuration clarity. Model field fetch modes give you control over how deferred fields are loaded and a way to make accidental N+1 queries raise instead of quietly firing, foreign keys can now push deletion down into the database itself, and email configuration moves from a pile of loose EMAIL_* settings to a single structured MAILERS dictionary. This release keeps the Python 3.12 minimum introduced in 6.0, but raises the floor on every supported database.

Release Highlights:

• Model field fetch modes: QuerySet.fetch_mode() accepts FETCH_ONE, FETCH_PEERS, or RAISE. FETCH_PEERS loads a missing field for every instance in the QuerySet at once, acting like an on-demand prefetch_related(), while RAISE raises FieldFetchBlocked so unintended queries fail loudly instead of silently.
• Database-level deletes: ForeignKey.on_delete gains DB_CASCADE, DB_SET_NULL, and DB_SET_DEFAULT, which emit a SQL ON DELETE clause and let the database handle cascades. These are faster than the Python-level equivalents but do not send pre_delete or post_delete signals.
• New MAILERS setting: configure several named email backends, each with its own options, and select between them by name.
• New database functions and aggregates: JSONNull for representing a top-level JSON null, UUID4 and UUID7 generators, and BitAnd, BitOr, and BitXor aggregates.
• Admin improvements: the form layout was reworked for accessibility, delete_confirmation_max_display caps how many related objects are listed on a delete confirmation, and admin actions accept a location parameter.
• Stronger password hashing: the default PBKDF2 iteration count rises to 1,500,000.
• Forms: a new Stylesheet asset object for media declarations, and FilePathField.set_choices().

Upgrade Gotchas:

• Requires Python 3.12, 3.13, or 3.14. This is unchanged from Django 6.0.
• Database minimums all move up: PostgreSQL 15 or later, MySQL 8.4 or later, MariaDB 10.11 or later, and SQLite 3.37 or later. Check your production database version before you start.
• Every EMAIL_* setting is deprecated in favour of MAILERS, along with mail.get_connection() and the connection, fail_silently, auth_user, and auth_password arguments to the email helpers. They keep working in 6.1 but are scheduled for removal in Django 7.0, so this is the release to start migrating.
• Several email calls that used to be ignored now raise: passing fail_silently, auth_user, or auth_password alongside connection raises TypeError, and a Bcc entry in headers raises ValueError.
• Cache keys changed for pages and fragments that vary on arguments. Expect a one-time wave of cache misses immediately after deploying.
• first() and last() no longer fall back to ordering by primary key when the ordering has been cleared, which can change which row you get back.
• SQL aliases are now quoted consistently. Raw SQL that referenced an unquoted alias may need updating.
• GIS drops PostGIS 3.1, GEOS 3.8 and 3.9, and GDAL 3.1 and 3.2.
• Removed in this release: the all argument to staticfiles.finders.find(), replaced by find_all; the request.user fallback in auth.login(); and the ordering argument on PostgreSQL aggregates, replaced by order_by.