Django 5.2 Released: What's New?

Django 5.2 LTS dropped in April 2025. This is the long-term support release you’ll want to migrate to—it’ll be supported until April 2028. Here’s what’s new.

LTS Stability

Django 5.2 is an LTS release:

• Security fixes until April 2028
• Bug fixes for ~16 months
• The stable foundation for production apps

New Features

Composite Primary Keys

Finally! Multi-column primary keys without hacks:

from django.db import models

class OrderItem(models.Model):
    order = models.ForeignKey(Order, on_delete=models.CASCADE)
    product = models.ForeignKey(Product, on_delete=models.CASCADE)
    quantity = models.IntegerField()
    
    class Meta:
        pk = models.CompositePrimaryKey("order", "product")

This was one of Django’s most requested features for legacy database integration.

Async ORM Improvements

More queryset methods now support async:

# New async methods
count = await Article.objects.acount()
exists = await Article.objects.filter(published=True).aexists()
first = await Article.objects.afirst()

# Async aggregations
from django.db.models import Count
result = await Author.objects.aannotate(
    article_count=Count('articles')
).aget(pk=1)

Enhanced Form Field Groups

Better control over field rendering:

class ContactForm(forms.Form):
    name = forms.CharField()
    email = forms.EmailField()
    
    def get_field_group_class(self, field):
        if field.errors:
            return "form-group error"
        return "form-group"

{% for field in form %}
  {{ field.as_field_group }}
{% endfor %}

Admin Improvements

Sidebar Customization:

@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    list_filter_sidebar = True  # Filters in sidebar
    sidebar_items = ['filters', 'actions', 'custom_widget']

Improved Search:

@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    search_fields = ['title', 'content']
    search_help_text = "Search by title or content"
    show_full_result_count = False  # Performance for large tables

Database Backend Improvements

PostgreSQL:

• Connection pool timeout configuration
• Improved JSON field indexing hints

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'OPTIONS': {
            'pool': {
                'min_size': 2,
                'max_size': 10,
                'timeout': 30,
            },
        },
    },
}

Template Improvements

New Filters:

{{ value|json_dumps }}
{{ items|sort_by:"name" }}
{{ text|truncate_html:100 }}

Migration Improvements

Better handling of field dependencies:

class Migration(migrations.Migration):
    operations = [
        migrations.AddField(
            model_name='article',
            name='slug',
            field=models.SlugField(db_default=models.functions.Lower('title')),
        ),
    ]

Breaking Changes

Minimum Python Version

Python 3.10+ required. Update your Python first:

python --version  # Must be 3.10+

Removed Deprecated Features

# Removed
from django.utils.encoding import force_text  # Use force_str
from django.conf.urls import url  # Use path/re_path

# Check for deprecation warnings in your tests
python -Wd manage.py test

Form Rendering Changes

Default form rendering updated. Check custom form templates.

Upgrade Guide

Step 1: Check Python

python --version  # 3.10+ required

Step 2: Update Dependencies

pip install Django==5.2
pip list --outdated  # Check other packages

Step 3: Run Deprecation Check

python -Wd manage.py check
python -Wd manage.py test

Step 4: Test Thoroughly

pytest --tb=short  # Full test suite
./manage.py check --deploy  # Deployment checklist

Step 5: Update CI/CD

# GitHub Actions example
- uses: actions/setup-python@v4
  with:
    python-version: '3.12'

Migration Checklist

## Django 5.2 LTS Upgrade

### Pre-Upgrade
- [ ] Python 3.10+ verified
- [ ] All tests passing on current version
- [ ] Dependencies compatibility checked
- [ ] Database backed up

### Upgrade
- [ ] pip install Django==5.2
- [ ] Fix deprecation warnings
- [ ] Run migrations
- [ ] Full test suite

### Post-Upgrade
- [ ] Staging deployment
- [ ] Manual QA
- [ ] Production deployment
- [ ] Monitor for issues

Should You Upgrade?

Upgrade now if:

• Starting new projects
• Currently on Django 5.0 or 5.1
• Need composite primary keys
• Want async improvements

Upgrade soon if:

• On Django 4.2 LTS (supported until Apr 2026)
• Large test suite passing

Wait with caution if:

• Critical dependencies not yet compatible
• Limited testing capacity

What’s Next

Django 6.0 is targeted for late 2025, continuing:

• Async ORM completion
• More admin enhancements
• Performance improvements

But for production stability, 5.2 LTS is your target.

Final Thoughts

Django 5.2 LTS is the release to bet on. Composite primary keys and async improvements are significant. The three-year support window gives stability.

Plan your migration. Test thoroughly. Enjoy the new features.

LTS: The foundation for the next three years.