Flask or Jinja2 crashes with cannot import name 'soft_unicode' from 'markupsafe'
ImportError: 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.
Fix it fast
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) "2Match what you see, then jump to its fix
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" flask3Verify
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
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/null2Fix
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.13Verify
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
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
pip install cryptography tries to compile and fails in a Docker build
fatal error: 'openssl/aes.h' file not found
cryptography ships prebuilt wheels.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Import of python_2_unicode_compatible fails after upgrading Django
Code importing django.utils.six fails on Django 3.0 and later
Django 3.0 removed the leftover Python 2 helpers, including python_2_unicode_compatible and django.utils.six.
2 causes, each with a fix