django-autocomplete-light v4 and v5

django-autocomplete-light has two current release lines with different jobs: v4 exists to provide the documented upgrade path from v3 and across supported Django versions, while v5 is where we can take the larger backward compatibility breaks that unblock the next API.

This post clarifies what each line is for, which one you should install, and where to find the upgrade documentation.

Short version

If you are already using django-autocomplete-light 3.x in production, upgrade to v4 first.

Version 4 is the smaller breaking-change line from v3. It keeps the Select2 integration and the existing project shape, while adding support for modern Django versions. It is the release line to use while you upgrade a project from Django 4.2 to Django 5.2.

Version 5 is the breaking-change line. It contains the changes that should not have landed in a v4 patch release. It is for projects that are ready to adapt their customizations and move to the cleaner lifecycle, but the v5 API is still open to change if we can reduce the backward compatibility break surface.

Why v4 exists

The purpose of v4 is boring on purpose: it should make upgrades possible without forcing an application rewrite. It may still require code changes when coming from v3, but those changes should be documented and limited enough that projects can move forward incrementally.

In particular, v4 is the line for projects that need a django-autocomplete-light version spanning the Django LTS upgrade path. If your application still runs on Django 4.2 and you want to reach Django 5.2, v4 is the bridge release line.

That matters because upgrade paths should be incremental:

• upgrade django-autocomplete-light from v3 to v4 and handle the documented v4 changes,
• keep the application working,
• then upgrade Django,
• then consider v5 when you are ready for its breaking changes.

Use the v3 to v4 upgrade guide here:

https://django-autocomplete-light.readthedocs.io/en/master/upgrade_from_v3_to_v4.html

Why v5 exists

Version 5 is where the backward-incompatible changes belong.

The main point of v5 is to remove old object lifecycle management from the jQuery side of the project and simplify the Python and JavaScript integration surface going forward. That is useful work, but it is not a patch-level change: projects with custom JavaScript initialization, custom widgets, or Python overrides may need to adapt.

That said, v5 is not an excuse to break more than necessary. We are still open to changing the v5 API before it settles if a different shape preserves the goal while making existing customizations easier to port.

This is especially important for advanced customizations around selected option rendering. For example, some projects use to_field_name="uuid" or filter selected choices with uuid__in instead of pk__in. These customizations should not require copying large blocks of internal widget code, so v5 is the right place to improve the extension points.

Use the v4 to v5 upgrade guide here:

https://django-autocomplete-light.readthedocs.io/en/master/upgrade_from_v4_to_v5.html

Compatibility

The important point is that v4 exists so users have an incremental path between the current Django LTS versions before taking the larger v5 changes.

django-autocomplete-light 3.12.x

• Django support: 4.2, 5.0, 5.1
• Python support: 3.11-3.13
• Purpose: existing v3 projects before the v4 upgrade.

django-autocomplete-light 4.x

• Django support: 4.2, 5.2
• Python support: 3.11-3.14
• Purpose: bridge release line for the v3 to v4 upgrade and Django 4.2 to 5.2 upgrades.

django-autocomplete-light 5.x

• Django support: 5.2, 6.0+
• Python support: 3.11-3.14
• Purpose: cleanup line for larger API and lifecycle changes.

If you are upgrading both Django and django-autocomplete-light, the intended path is to move through v4 first. Do not jump directly from an old v3 project to v5 unless you are ready to handle both upgrade steps at once.

Which version should I use?

Use v4 if:

• you are upgrading from django-autocomplete-light 3.x,
• you need the smallest documented path from v3 across Django 4.2 and Django 5.2,
• you rely on existing Select2 behavior,
• you have production customizations and want the smallest change first.

Use v5 if:

• you are starting a new project,
• you already completed the v4 upgrade,
• you are ready to handle backward-incompatible customization changes,
• you want to test the new API and help reduce the final break surface,
• you want the cleaner lifecycle and future API direction.

About the release confusion

A backward-incompatible change was released as 4.0.1. That was a mistake. It has been moved to the v5 line so projects pinned to v4 can stay on the compatibility path.

The v4 line is now the place for the smaller v3-to-v4 upgrade path and compatibility fixes, including Django 4 support. The v5 line is the place for larger intentional breaking changes.

Going forward, the rule is simple:

• v4 is for the documented v3 upgrade path and Django upgrade bridging,
• v5 is for larger breaking changes and cleanup,
• release documentation should say which Django versions are supported,
• package releases should be yanked rather than deleted when possible, so pinned deployments fail less surprisingly.

If a release unexpectedly breaks your builds, please keep in mind that my phone number is present in the footer of this blog/site. The django-autocomplete-light README also has a section to help people reach me quickly in that situation. I really do want to know as soon as possible when a release breaks production upgrade paths, because that is the moment where a fast yank, patch, or clarification can save a lot of people time.

Documentation

The upgrade pages are:

• Upgrade from v3 to v4
• Upgrade from v4 to v5

The compatibility table is documented here:

https://django-autocomplete-light.readthedocs.io/en/master/#compatibility

If something in the upgrade path is still unclear, please open an issue with the versions of Django and django-autocomplete-light you are running, the target versions, and any widget or JavaScript customizations involved. For v5 in particular, examples of customizations that became harder than necessary are useful: we can still change the API if that makes the upgrade path smaller.