Maaz Zindani

Loading the index…

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

Flask or Jinja2 crashes with cannot import name 'soft_unicode' from 'markupsafe'

ErrorImportError: cannot import name 'soft_unicode' from 'markupsafe'

Short answer

MarkupSafe 2.1.0 deleted the old soft_unicode helper. Jinja2 2.x still imports it, so a fresh install that pulls the newest MarkupSafe next to an old Jinja2 fails at import time. Upgrade Jinja2 to 3.x (and the frameworks that pin it), or, if you cannot yet, pin MarkupSafe to a version below 2.1.

  • Applies to Python 3.12, MarkupSafe 2.1 and newer, Jinja2 2.11 and 3.x, pip 24
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print which versions of the two packages are installed in the environment that crashes. The mix of a new MarkupSafe and an old Jinja2 is the whole story.

    python -m pip list 2>/dev/null | grep -iE "^(jinja2|markupsafe|flask|werkzeug) "
  2. 2Match what you see, then jump to its fix

    1. 1Jinja2 shows 2.x in the list and MarkupSafe shows 2.1.0 or higherAn old Jinja2 (2.x) is installed next to a new MarkupSafeFix
    2. 2requirements.txt pins Jinja2==2.x (or a framework of that age) and the image was rebuilt without pinning MarkupSafeA legacy project must keep its old Jinja2 for nowFix

What does the error look like?

  • ImportError: cannot import name 'soft_unicode' from 'markupsafe'

Cause 1 of 2

An old Jinja2 (2.x) is installed next to a new MarkupSafe

1Check

The MarkupSafe changelog lists soft_unicode as removed in 2.1.0 and names soft_str as the replacement. Jinja2 2.11.3 still has the line from markupsafe import soft_unicode in its filters module. Ask pip which package holds Jinja2 back.

python -m pip show jinja2 | grep -E "^(Version|Required-by)"
python -m pip show markupsafe | grep "^Version"

2Fix

Upgrade Jinja2 to a 3.x release. Jinja2 3.0.0 no longer imports soft_unicode. If Flask, Werkzeug or another package pins Jinja2 below 3, upgrade that package in the same command.

python -m pip install --upgrade "jinja2>=3.0" flask

3Verify

The import that crashed now works.

python -c "import jinja2, markupsafe; from importlib.metadata import version as v; print(v('jinja2'), v('markupsafe'))"

Confirmed by markupsafe.palletsprojects.com

Did this fix it?

Cause 2 of 2

A legacy project must keep its old Jinja2 for now

1Check

An unpinned markupsafe line, or no line at all, lets pip choose the newest release at build time. Search the requirements files for it.

grep -rniE "markupsafe|jinja2" requirements*.txt pyproject.toml 2>/dev/null

2Fix

Add an upper bound so pip picks a MarkupSafe release from before the removal. Treat this as a bridge and plan the Jinja2 upgrade.

# requirements.txt
jinja2==2.11.3
markupsafe<2.1

3Verify

Reinstall from the file in a clean environment and import Jinja2.

python -m pip install --force-reinstall -r requirements.txt
python -c "import jinja2; print('import ok')"

Confirmed by pip.pypa.io

Did this fix it?

How do I stop it coming back?

  • Pin direct dependencies and use a lock or constraints file so a rebuild installs the versions you tested.
  • Read the changelog of a library before raising its upper bound, and watch for lines that say Remove.

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.