Skip to main content

How to Resolve Python Error "ImportError: cannot import name 'soft_unicode' from 'markupsafe'"

When working with Python web frameworks like Flask or templating engines like Jinja2 (which rely on the markupsafe library for secure HTML string handling), you might encounter the ImportError: cannot import name 'soft_unicode' from 'markupsafe'. This error specifically indicates that code is trying to import soft_unicode, a function that was removed in markupsafe version 2.1.0.

This guide explains why this deprecation causes the error and provides the primary solutions: pinning markupsafe to an older version or updating the dependent libraries/code.

Understanding the Error: Deprecation of "soft_unicode"​

The markupsafe library is essential for securely handling strings in web applications, particularly for escaping HTML to prevent XSS attacks and marking strings as "safe" to render unescaped.

  • soft_unicode: This was a function in older versions of markupsafe used to convert objects to Unicode strings while trying to preserve Markup objects (HTML-safe strings) without double-escaping them.
  • Deprecation & Removal: As stated in the markupsafe changelog, soft_unicode was deprecated and then removed starting with version 2.1.0. It was effectively replaced by soft_str.

The ImportError occurs when your code, or more commonly, a library your project depends on (like an older version of Flask, Jinja2, or AWS SAM CLI), tries to execute from markupsafe import soft_unicode but you have markupsafe version 2.1.0 or newer installed, where soft_unicode no longer exists.

Cause: Attempting to Import soft_unicode with markupsafe >= v2.1.0​

The direct cause is an import statement for soft_unicode running in an environment where the installed markupsafe version is 2.1.0 or higher.

# error_scenario.py (assuming markupsafe >= 2.1.0 is installed)

try:
    # ⛔️ ImportError: cannot import name 'soft_unicode' from 'markupsafe'
    from markupsafe import soft_unicode
    print("Imported soft_unicode (unexpected with new markupsafe).")
except ImportError as e:
    print(e)

Solution 1: Pin markupsafe to Version 2.0.1 (Common Workaround)​

If you cannot immediately update the code or library causing the outdated import, the most common workaround is to downgrade markupsafe to the last version that included soft_unicode, which is 2.0.1.

Installing markupsafe==2.0.1 via Pip​

Run this command in your terminal (activate your virtual environment if you use one):

pip install markupsafe==2.0.1

# Or use pip3 / python -m pip etc.:
pip3 install markupsafe==2.0.1
python -m pip install markupsafe==2.0.1
py -m pip install markupsafe==2.0.1 # Windows

# For Jupyter Notebooks:
!pip install markupsafe==2.0.1

Pinning in requirements.txt​

To make this permanent for your project, add or modify the line in your requirements.txt:

# requirements.txt
# ... other dependencies ...
markupsafe==2.0.1
# ... other dependencies ...

Then, run pip install -r requirements.txt.

Forcing Reinstallation​

If pip indicates markupsafe==2.0.1 is already satisfied (but you suspect a mixed-up environment), you can force a reinstall:

pip install markupsafe==2.0.1 --force-reinstall

Pip might show a dependency resolver error during this process if other packages require a newer markupsafe. The package usually still installs, but this highlights that pinning is a workaround, and updating dependencies is better long-term.

Solution 2: Update Dependent Libraries (e.g., Flask, Jinja2, AWS SAM CLI)​

This is the preferred long-term solution. The ImportError often arises because an older version of a library like Flask, Jinja2, or a tool like AWS SAM CLI is trying to use the deprecated soft_unicode. Newer versions of these libraries have typically been updated to use markupsafe's modern API (e.g., using soft_str or other internal changes).

  • Flask & Jinja2:

    pip install --upgrade Flask Jinja2 markupsafe

    (Modern Flask often bundles compatible versions of Jinja2 and MarkupSafe).

  • AWS SAM CLI: Old versions were known to cause this. Upgrade to the latest SAM CLI. It's generally recommended to install/update SAM CLI using the official OS-specific installers rather than just pip. If you did use pip:

    pip install --user --upgrade aws-sam-cli

    For GitHub Actions or CI/CD, ensure you're using a recent aws-actions/setup-sam version (e.g., v1.38.0 or later, as versions prior to that might have bundled older markupsafe).

Solution 3: Update Your Own Code (Replace soft_unicode with soft_str)​

If the from markupsafe import soft_unicode line is in your own custom code, you should update it to use the modern equivalent, soft_str, which was introduced to replace soft_unicode.

# Old code (markupsafe < 2.1.0)
# from markupsafe import soft_unicode # ⛔️ This causes the error

# ✅ New code (markupsafe >= 2.0.0 approx, canonical for >=2.1.0)
from markupsafe import soft_str, escape

# Example usage:
potentially_markup_object = escape("<Hello>") # This is a Markup object
text_value = "World"

# soft_str will preserve Markup objects as Markup, others as str
print(f"soft_str on Markup: {soft_str(potentially_markup_object)}") # Output: Markup('&lt;Hello&gt;')
print(f"soft_str on str: {soft_str(text_value)}")                   # Output: 'World'

# Using escape with str() vs soft_str() on a Markup object:
print(escape(str(potentially_markup_object)))       # Would double-escape: &amp;lt;Hello&amp;gt;
print(escape(soft_str(potentially_markup_object)))  # Correctly: &lt;Hello&gt; (already safe)
note

Make sure your markupsafe is reasonably up-to-date if you switch to soft_str (pip install --upgrade markupsafe).

Verifying markupsafe Version (pip show)​

After attempting a fix, check which version of markupsafe is actually active in your environment:

pip show markupsafe
# Or use pip3 / python -m pip show

This will confirm if your pinning or upgrade was successful.

Conclusion​

The ImportError: cannot import name 'soft_unicode' from 'markupsafe' occurs because soft_unicode was removed in markupsafe v2.1.0.

The primary solutions are:

  1. Pin markupsafe to 2.0.1: Use pip install markupsafe==2.0.1. This is a common workaround if you cannot modify the code or libraries causing the old import.
  2. Update Dependent Libraries: The preferred long-term fix. Upgrade libraries like Flask, Jinja2, AWS SAM CLI, Dash, etc., as newer versions are generally compatible with modern markupsafe.
  3. Update Your Own Code: If from markupsafe import soft_unicode is in your code, replace it with from markupsafe import soft_str and ensure markupsafe is up-to-date.

Always use virtual environments to manage dependencies and avoid conflicts between projects.

Table of Contents