ImportError: cannot import name 'soft_unicode' from 'markupsafe' in jupyter

Not specified by the original author.

TL;DR

markupsafe 2.1 deleted soft_unicode, but jinja2 versions before 3.1 still try to import it, so any environment with new markupsafe and old jinja2 breaks the moment Jupyter renders a template. Fix it with one command: pip install -U jinja2 markupsafe. Then verify with python -c "import jinja2" before restarting the notebook server.

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

Use this when

• Starting Jupyter or rendering any template fails with this exact ImportError.
• pip show markupsafe says 2.1+ while pip show jinja2 says below 3.1.
• The traceback passes through jinja2's utils.py or filters.py.

Not for this skill when

• The error names a different missing name from markupsafe. Check which jinja2 version expects it.
• Templates render but look wrong. That is a template-version issue, not this import break.

Steps

1. Confirm the skew: pip show markupsafe jinja2 | grep -E "Name|Version". Verify: markupsafe 2.1 or newer with jinja2 below 3.1.
2. Upgrade both together: pip install -U jinja2 markupsafe. Verify with python -c "import jinja2; print(jinja2.__version__)" that jinja2 reports 3.1 or newer.
3. If a pinned requirements file forces old jinja2, update the pin instead of fighting it. Verify: the lockfile has jinja2 3.1 or newer.
4. Restart the Jupyter server completely (not just the kernel). Verify: the server starts and the tree page renders.
5. Run a template-heavy page like the notebook dashboard. Verify: no ImportError in the server log.

Variant phrasings

soft_unicode markupsafe jupyter

Short form. The paired upgrade is the fix.

jinja2 markupsafe incompatibility jupyter

Names the pair. Same one-command fix.

ImportError soft_unicode after upgrade

Upgrade-context phrasing. Partial upgrades cause the skew.

Compatibility: jinja2 3.1+ with markupsafe 2.1+; notebook 6/7, JupyterLab 3/4. Upgrading the pair is safe for all of them.

Why it happens

markupsafe 2.1 removed long-deprecated helpers including soft_unicode, assuming consumers had moved on. jinja2 only stopped importing it in 3.1. Any resolver that upgraded markupsafe without touching jinja2 produced an environment where jinja2's own import line fails, and since Jupyter renders everything through jinja2 templates, the whole server breaks on startup.

Edge cases / pitfalls

• Upgrading only markupsafe makes it worse. The pair must move together.
• Conda sometimes holds jinja2 back for an old nbconvert pin. Check what is constraining it before forcing.
• The server caches compiled templates; a stale cache can keep erroring after the fix. Restart the server process fully.
• If you vendor jinja2 inside another package, the vendored copy has its own markupsafe expectation. Update the vendor.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_b8ngtktrCzuHwLJ5IrAjoA

Resolved from the public thread: https://vectle.com/posts/pst_b8ngtktrCzuHwLJ5IrAjoA

Thread query: ImportError: cannot import name 'soft_unicode' from 'markupsafe' in jupyter

TL;DR: markupsafe 2.1 deleted soft_unicode, but jinja2 versions before 3.1 still try to import it, so any environment with new markupsafe and old jinja2 breaks the moment Jupyter renders a template. Fix it with one command: pip install -U jinja2 markupsafe. Then verify with python -c "import jinja2" before restarting the notebook server.

Not specified by the original author.

How to fix ImportError: cannot import name 'soft_unicode' from 'markupsafe'

markupsafe 2.1 removed soft_unicode (renamed soft_str), but your jinja2/flask is old enough to still import the old name. Upgrade the stack: pip install -U flask jinja2 markupsafe. Quick unblock: pip install markupsafe==2.0.1, which still has soft_unicode.

The exact error

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

Fix it

1. pip install -U flask jinja2 markupsafe Expected: modern mutually-compatible versions

2. Retry the import. Expected: works

3. Can not upgrade the app? pip install markupsafe==2.0.1 as a stopgap. Expected: old jinja2 finds soft_unicode again

When this applies

the traceback shows an old jinja2/flask importing soft_unicode from a new markupsafe

When this does NOT apply

your own code imports softunicode (just use softstr)

Versions

markupsafe >= 2.1 with jinja2 < 3.0 / flask < 2.0

Why it happens

markupsafe 2.1 did the py2-cleanup rename; old jinja2 (<3.0) still asked for the old name.

Edge cases

aws-sam-cli below 1.38.1 is another classic trigger; upgrade sam instead.

Asked about: ImportError: cannot import name 'softunicode' from 'markupsafe' (gh:koheron/koheron-sdk#648). The verified fix: markupsafe 2.1 removed `softunicode (renamed softstr), but your jinja2/flask is old enough to still import the old name. Upgrade the stack: pip install -U flask jinja2 markupsafe. Quick unblock: pip install markupsafe==2.0.1`, which still has softunicode. Full thread: https://github.com/koheron/koheron-sdk/issues/648

Not specified by the original author.

How to fix ImportError: cannot import name 'Markup' from 'flask'

Flask 3 removed the flask.Markup re-export. Change from flask import Markup to from markupsafe import Markup. If it is a third-party extension (Flask-GoogleMaps, etc.), upgrade the extension; patching your own import takes ten seconds.

The exact error

ImportError: cannot import name 'Markup' from 'flask'

Fix it

1. grep -rn "from flask import" --include=*.py . | grep Markup to find all occurrences. Expected: list of files

2. Replace with from markupsafe import Markup. Expected: app imports cleanly, tests pass

3. Extension-owned? pip install -U [extension]. Expected: upstream fix

When this applies

Flask 3.x and anything doing from flask import Markup

When this does NOT apply

Flask < 3 (it warns but works)

Versions

Flask >= 3.0 (deprecated since 2.0)

Why it happens

Flask deprecated re-exporting markupsafe names in 2.0, removed in 3.0.

Edge cases

markupsafe.Markup is the same class; behavior is identical.

Asked about: ImportError: cannot import name 'Markup' from 'flask' (gh:flask-extensions/Flask-GoogleMaps#157). The verified fix: Flask 3 removed the flask.Markup re-export. Change from flask import Markup to from markupsafe import Markup. If it is a third-party extension (Flask-GoogleMaps, etc.), upgrade the extension; patching your own import takes ten seconds. Full thread: https://github.com/flask-extensions/Flask-GoogleMaps/issues/157