Title: Updating a Django project from v2 to v6
Slug: updating-a-django-project-from-v2-to-v6
Date: 2025-12-28 16:50:00
Author: Kartones
Lang: en
Tags: Development, Python, Migrations, Django
og_image:
Description: Upgrading a long-neglected Django project turned out to be far smoother than expected, reinforcing the Django project's strong commitment to backward compatibility.


Despite not having worked with it actively in recent years, I like the Python [Django](https://www.djangoproject.com/) framework a lot. It is a very complete ORM + web package, while at the same time being flexible enough to allow you to discard many of the components you don't need. I built a project to experiment with it some time ago, [Finished Games](https://github.com/Kartones/finished-games), but it was in maintenance mode due to being stuck in v2.2 of the framework.

Today I decided to remove the main blocker, a fancy autocomplete search box that breaks in Django 3 and also forced me to add a few hacks here and there. I replaced it with a simpler but purely HTML5 and JavaScript solution proposed in [this article](https://www.htmhell.dev/adventcalendar/2025/27/). If you're interested in the details, you can check [the corresponding pull request](https://github.com/Kartones/finished-games/pull/132).

Now that the path was clear, I went on and updated to Django 3.2. There were a few breaking changes, but nothing major. [The PR](https://github.com/Kartones/finished-games/pull/133) looks small, but I also updated almost all the packages to their latest versions. I also had some CSS issues in the admin site, so I a) deleted my tiny customizations and b) hide the new navigation sidebar that was rendering not too well.

The update to Django 4.x was the easiest one ([related PR](https://github.com/Kartones/finished-games/pull/134)). Not a single issue! I also removed the `django-debug-toolbar`, as it simplifies the code and can always be added back on-demand if needed (e.g. to debug a nasty issue).

Once in v4, updating to v5 had an easily fixable `STATIC_ROOT` issue (now seems to be required even for non-production) and a few more minor CSS issues in the Django Admin (again), so I decided to go all-in and directly bump to the latest Django 6.0 ([resulting PR](https://github.com/Kartones/finished-games/pull/135/)). Along the way, I also updated the container's Python version to 3.14.

The CSS rendering problems persist on the project after updating to Django 6, but are very specific, so I manually fixed the CSS issues by hiding two of the offenders and fixing the third one (a button). If I have some spare time, I will dig into why a now "vanilla" admin site has such hurdles, but it is not high on my priority list.

As a conclusion, kudos to the Django project folks for making so few breaking changes, I wasn't sure I would be able to advance so much. As for the admin site, my suggestion is to stick to the default one regarding UX/styling, or go to the other extreme and fully replace it, so you don't depend on the base components.