Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Import of python_2_unicode_compatible fails after upgrading Django

Errorpython_2_unicode_compatible import error after upgrading Django

Short answer

Django 3.0 removed the leftover Python 2 helpers, including python_2_unicode_compatible and django.utils.six. Code that still imports them fails on any current Django. Delete the decorator from your models, switch the import to six if you must keep it, or upgrade the old third-party package.

  • Applies to Django 5.2, Python 3.12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find every place that still uses the removed helpers, in your code and in installed packages.

    grep -rn "python_2_unicode_compatible\|django.utils.six" --include=*.py .
    python -m pip show django | head -n 2
  2. 2Match what you see, then jump to its fix

    1. 1The traceback points at a file in your projectYour own models still use the decoratorFix
    2. 2The traceback points into site-packagesAn old third-party package imports django.utils.sixFix

What does the error look like?

  • python_2_unicode_compatible import error after upgrading Django
  • Code importing django.utils.six fails on Django 3.0 and later

Cause 1 of 2

Your own models still use the decorator

1Check

The Django 3.0 release notes list django.utils.encoding.python_2_unicode_compatible among the removed APIs, an alias of the one in six. On Python 3, __str__ already returns text, so the decorator does nothing useful.

grep -rn "python_2_unicode_compatible" --include=*.py .

2Fix

Delete the import and the decorator line. Keep the __str__ method as it is.

# before
from django.utils.encoding import python_2_unicode_compatible

@python_2_unicode_compatible
class Animal(models.Model):
    def __str__(self):
        return self.name

# after
class Animal(models.Model):
    def __str__(self):
        return self.name

3Verify

Django starts without the import error.

python manage.py check

Confirmed by docs.djangoproject.com

Did this fix it?

Cause 2 of 2

An old third-party package imports django.utils.six

1Check

The release notes say django.utils.six was removed and that code should drop it or use the six package directly. A package that was written for Django 2 and never updated still imports it.

python -m pip list | grep -i six

2Fix

Upgrade that package to a release that supports your Django version. If no such release exists, replace the package. Installing six alone does not fix an import of django.utils.six.

python -m pip install --upgrade the-package-name

3Verify

Run the project checks.

python manage.py check

Confirmed by docs.djangoproject.com

Did this fix it?

How do I stop it coming back?

  • Read the release notes of each Django version before upgrading and run the tests with python -Wa manage.py test.
  • Pin dependencies in a lock file and upgrade them together with Django.
  • Drop packages that are no longer maintained.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.