If you've been building with Django for years, you’ve probably experienced the upgrade jitters: will your models break, will migrations hang, will something subtle betray you in production?

With version 5.2, Django sets itself up as the next “safe platform” release: it’s designated as a long-term support (LTS) version, so picking it means you’re investing in stability and new features (Django Project).

But don’t think of it as simply a maintenance release: 5.2 introduces several features that shift how you work with Django, from your shell workflow to database modelling.

This article walks through the key changes you’ll want to know about, and flags what you might need to adjust when upgrading.

Breaking Changes (High-Impact)

These are changes that can significantly affect your codebase or deployment, and need intentional planning.

End of mainstream support for 5.1

With 5.2’s release, Django 5.1 has reached the end of mainstream support. (Django Project) That means if you’re on 5.1 (or earlier), you should plan your upgrade path fairly soon to keep receiving security and data-loss fixes.

If you are running tests in your Django project (which you should), you can test the upgrade with:

# Upgrade your project safely
pip install "django>=5.2,<5.3"

# Then run tests
python manage.py test

One of the headline features of 5.2 is the introduction of CompositePrimaryKey via django.db.models.CompositePrimaryKey.

While this is a new capability (rather than a removal), it does impose limitations and migration constraints that can “break” assumptions:

  • You cannot migrate a model to or from using a composite primary key (i.e., switching a model later)
  • Relationship fields (ForeignKey, ManyToManyField, etc) can not target a model with composite PK yet (without workarounds).

If you’re working with legacy databases that use composite keys, this is very good news. But if you plan to retrofit composites on an existing model, you’ll need to plan carefully (or avoid doing so), treat it as a major architectural change.

For example:

from django.db import models

# Student model
class Student(models.Model):
    name = models.CharField(max_length=100)

# Course model
class Course(models.Model):
    title = models.CharField(max_length=100)

# Enrollment model with composite primary key
class Enrollment(models.Model):
    pk = models.CompositePrimaryKey("student_id", "course_id")
    student = models.ForeignKey("Student", on_delete=models.CASCADE)
    course = models.ForeignKey("Course", on_delete=models.CASCADE)
    enrolled_on = models.DateField(auto_now_add=True)

Shell automatic imports

Another big change: the manage.py shell command now automatically imports all models from all installed apps by default.

While this is primarily a developer‐experience change, it can “surprise” code that relies on different behaviours (for example, custom shell commands expecting no pre-imports).

You can disable it via --no-imports, and customise imports if needed.

For example:

# Now, models are auto-imported:
python manage.py shell

# You can use models directly
>>> User.objects.first()

# To disable automatic imports
python manage.py shell --no-imports

URL reversal augmentation: reverse() & reverse_lazy() now accept query and fragment keyword args

Prior to 5.2, building a URL with a query string or fragment required manual concatenation and URL-encoding. Now you can simply pass query={…} and fragment='…'.

While this isn’t a breaking removal, it does mean you might update your URL-building code.

Before 5.2:

from django.urls import reverse
url = reverse("blog:post_detail", args=[42]) + "?preview=true#comments"

Now in 5.2:

from django.urls import reverse
url = reverse(
    "blog:post_detail",
    args=[42],
    query={"preview": "true"},
    fragment="comments"
)
# /blog/42/?preview=true#comments

Get my free Python One-Liner Cheat Sheet, a downloadable PDF packed with idiomatic tricks, clean patterns, and productivity boosters.

Medium-Impact Changes

These changes improve workflows, add new features, or adjust internal behaviour, you’ll likely adopt them gradually rather than be forced to.

New form widgets: ColorInput, SearchInput, TelInput

Django 5.2 adds new built-in form widgets aligned with HTML5 input types.

  • ColorInput for <input type="color">
  • SearchInput for <input type="search">
  • TelInput for <input type="tel">

These provide better semantics and accessibility. If your project uses custom widgets or polyfills, you may want to evaluate whether to adopt these native ones.

For example:

from django import forms

class ProfileForm(forms.Form):
    favorite_color = forms.CharField(widget=forms.ColorInput)
    phone = forms.CharField(widget=forms.TelInput)
    search = forms.CharField(widget=forms.SearchInput)

HttpResponse.text property

Testing code frequently decodes response.content.decode() to check string content.

Django 5.2 introduces response.text, a convenience property returning the decoded text. This is a nice productivity win in tests.

Instead of:

self.assertIn("Welcome", response.content.decode())

You can now do:

self.assertIn("Welcome", response.text)

HttpRequest.get_preferred_type() for content negotiation

A new method on HttpRequest lets you query the preferred media type(s) the client accepts.

For APIs or content-negotiating views, this provides a more robust built-in approach than custom parsing.

For example:

def api_view(request):
    preferred = request.get_preferred_type(["application/json", "text/html"])
    if preferred == "application/json":
        return JsonResponse({"message": "JSON response"})
    return HttpResponse("<h1>HTML response</h1>")

BoundField customisation at multiple levels

If you’ve ever needed to customise how form fields are bound, rendered or validated, 5.2 expands the surface: you can now specify BaseRenderer.bound_field_class at project level, Form.bound_field_class at form level or Field.bound_field_class at field level.

This enhances form flexibility, especially for UI libraries or design systems built on Django forms.

For example:

from django import forms
from django.forms.boundfield import BoundField

class CustomBoundField(BoundField):
    def label_tag(self, contents=None, attrs=None, label_suffix=None):
        return f"<label class='custom-label'>{self.label}</label>"

class MyForm(forms.Form):
    name = forms.CharField()
    bound_field_class = CustomBoundField

Values/values_list ordering preservation

An update improves QuerySet.values() and values_list() behaviour to maintain the field order specified in the query (previous versions could reorder).

If your code assumes a particular ordering of fields in .values(), you might find some behaviour becomes more consistent (which is good), but test to ensure nothing depended on the old unspecified ordering.

For example:

qs = User.objects.values("id", "username", "email")
# Always returns fields in that order now

Learn how to deploy Django apps with confidence using my step-by-step guide to simplifying Django deployments: https://developer-service.blog/django-deployment-simplified-leveraging/

Low-Impact / Quality-of-Life Changes

These tweaks are unlikely to require code changes, but are useful to know about and adopt when convenient.

  • The admin/base.html template now offers a new block extrabody for inserting custom HTML just before </body>.