Skip to main content

Python Django: How to Resolve "ImportError: cannot import name 'force_text' from 'django.utils.encoding'"

When upgrading your Django project to version 4.0 or newer, you will likely encounter the ImportError: cannot import name 'force_text' from 'django.utils.encoding'. This error occurs because force_text, which was a utility function in older Django versions, was officially removed in Django 4.0.

This guide will explain why this function was removed and provide three clear solutions to resolve the error, ordered from the most recommended long-term fix to a temporary workaround. You will learn how to update your own code, how to upgrade third-party dependencies, and, if necessary, how to temporarily downgrade Django.

Understanding the Error: Deprecation and Removal in Django 4.0​

In previous versions of Django, both force_text and force_str existed. The force_text function was primarily an alias for force_str that was kept for backward compatibility, particularly for codebases that needed to support Python 2.

With Django 4.0, support for older Python versions was dropped, and the codebase was cleaned up. As part of this cleanup, the redundant force_text alias was removed. The correct function to use is now force_str.

Solution 1: Update Your Own Code (Replace force_text with force_str)​

If the error originates from your own project's code, the fix is straightforward: you must replace all occurrences of force_text with force_str.

Example of code causing the error:

# This import will fail in Django 4.0+
from django.utils.encoding import force_text

def my_function(some_bytes):
    # This usage will also fail
    text_representation = force_text(some_bytes)
    return text_representation

Solution: change the import statement and the function call to use force_str.

# ✅ Correct: Use force_str instead
from django.utils.encoding import force_str

def my_function(some_bytes):
    text_representation = force_str(some_bytes)
    return text_representation

Solution 2: Upgrade Third-Party Django Packages​

Often, this ImportError does not come from your own code but from an outdated third-party Django package that you are using. If a library has not been updated to be compatible with Django 4.0, it will still try to import force_text.

Solution: the solution is to upgrade these packages to their latest versions, as their maintainers have likely already patched them for Django 4.0 compatibility.

Common packages that caused this issue include:

  • graphene-django
  • django-elasticsearch-dsl
  • djangorestframework-simplejwt
  • django-smart-selects

You can upgrade them individually:

pip install --upgrade djangorestframework-simplejwt
pip install --upgrade graphene-django
# etc.
note

If you manage your project with a requirements.txt file, you may need to update your version constraints. For example, change djangorestframework-simplejwt==4.8.0 to djangorestframework-simplejwt>=5.0.0 to allow pip to install a compatible version. After updating your file, run: pip install -r requirements.txt --upgrade

Solution 3: Downgrade Django to a Version Below 4.0 (Temporary Fix)​

If you cannot immediately update your code or your dependencies, you can downgrade Django to the latest version in the 3.x series as a temporary workaround. This will allow your project to continue running until you have time to perform the necessary upgrades.

Solution: use pip to install a version of Django that is less than 4.0.

pip install "django<4.0" --force-reinstall

This command will install the latest available version from the 3.2.x series, where force_text still exists.

warning

This is not a long-term solution. By pinning your project to an older version of Django, you will miss out on important security updates, bug fixes, and new features. You should plan to upgrade to a supported version as soon as possible.

Conclusion​

If the error is in...The best solution is...
Your own project codeManually replace all imports and uses of force_text with force_str.
A third-party packageUpgrade the package to its latest version (e.g., pip install --upgrade <package-name>).
An unmaintained package or you need a quick fixTemporarily downgrade Django to a version below 4.0 (pip install "django<4.0").

For a healthy and secure project, the recommended approach is always to keep your code and dependencies up-to-date with the latest stable versions of Django.

Table of Contents