# Fix "cannot import name 'soft_unicode' from 'markupsafe'"

Yes. An agent finds the unbounded MarkupSafe requirement behind the ImportError, proves which fix your Flask version can take, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/fix-markupsafe-soft-unicode-import-error/markupsafe/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts from the install, because this error is produced by the resolver and not by any line of your code. In a project like Widdershin/flask-desktop, `requirements.txt` pins `Flask==1.0`, `Jinja2==2.11.3`, `Werkzeug==0.15.5` and `itsdangerous==0.24`, and leaves one line open: `MarkupSafe>=1.1.1`. `setup.py` reads that file into `install_requires`, so everyone who installs the package inherits the open range. A fresh environment today resolves MarkupSafe 3.0.4, and `import flask` stops inside Jinja2 at `jinja2/filters.py` line 13, `from markupsafe import soft_unicode`. MarkupSafe renamed that function to `soft_str` and removed the old name in 2.1.0. Jinja2 2.11.3 still asks for it.

Next it works out which Python the project can install on at all, since that limits the choices. Here `PySide2==5.15.2` declares that it needs a Python below 3.10, so the agent builds its environment on 3.9, installs the file as written and quotes the traceback. The project has no tests and no CI workflow, so it writes a ten-line check of its own: a Flask app with one route that renders a template containing a value with angle brackets, called through `app.test_client()`. That exercises the Flask, Jinja2 and MarkupSafe chain without opening the Qt window that `webui/webui.py` creates.

Then it tries each fix and keeps the evidence. Capping the range as `MarkupSafe>=1.1.1,<2.1` resolves 2.0.1, and the check renders and escapes the value. Raising Jinja2 alone does not work: with Jinja2 3 installed, Flask 1.0 fails sooner, with `cannot import name 'Markup' from 'jinja2'`, because that old Flask imports `Markup` and `escape` from Jinja2 and newer Jinja2 no longer exports them. Moving the whole set forward together does work on the same Python 3.9: Flask 3.1.3 with Jinja2 3.1.6 and MarkupSafe 3.0.4 passes the check, and `webui/webui.py` still imports, since its only use of Flask is `flask_app.run(debug=debug, host=host, port=port, use_reloader=False)`.

The prompt decides which of the two working fixes the pull request carries. By default the agent makes the smallest change that restores the install, the one-line cap, and writes up the full upgrade as a second option with what it tested and what it could not. It does not add `soft_unicode` back with a shim or patch files inside `site-packages`.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "This project fails on a fresh install with: ImportError: cannot import name 'soft_unicode' from 'markupsafe'. Fix it. Read every dependency file (requirements files, setup.py, setup.cfg, pyproject.toml, lock files) and list the version constraint on Flask, Jinja2, MarkupSafe, Werkzeug and itsdangerous, and say which of them are unpinned or open-ended. Work out which Python versions the pinned packages can install on and use one of them. In a clean virtual environment install the project exactly as its files say, reproduce the error and quote the traceback and the resolved versions. If the project has tests, run them; if it has none, write the smallest check that imports the app and renders one template through the test client, without starting a server or a GUI. Try these fixes in separate environments and report each result: an upper bound on MarkupSafe that still has the removed name; upgrading Jinja2 only; upgrading Flask, Jinja2, Werkzeug, itsdangerous and MarkupSafe together. Put the smallest fix that passes the check in the pull request, and describe the full upgrade as a follow-up with what you tested. Do not vendor or monkeypatch markupsafe, and do not edit installed packages. Open a pull request with the traceback before, the resolved versions after, and the check's output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that changes one line of `requirements.txt`, from `MarkupSafe>=1.1.1` to `MarkupSafe>=1.1.1,<2.1`. Because `setup.py` builds `install_requires` from that file, the same line fixes `pip install` of the package for its users. The description quotes the traceback ending in `jinja2/filters.py`, the versions the resolver chose before and after, and the output of the render check on both.

Below that it lays out the larger option as a table: each of the five web packages, its pinned version and the version the upgrade test resolved. It states plainly what the upgrade test covered, one rendered template and an import of `webui.webui`, and what it did not, which is the Qt window itself. A reviewer who owns a desktop machine is the one who can run `examples/test_app.py` and watch the window open.

What a reviewer checks before merging is the cap's cost. MarkupSafe 2.0.1 publishes wheels for CPython 3.6 through 3.10 and nothing newer, so the one-line fix holds only while the project stays on those interpreters. Here PySide2 already keeps it below 3.10, and the description says that the two limits should be lifted together.

## Run it on every image build that fails on this import

This error arrives without a commit: an image is rebuilt, the resolver picks a newer MarkupSafe, and the app stops at import. Catch it where the build runs. Add an automation with a `webhook` trigger and the prompt above to the Project that holds the repository, then add a step to the build workflow that runs `python -c "import flask"` after the install. When that step fails and its output contains `soft_unicode`, a following step posts the output to the trigger's URL with `Authorization: Bearer` and the trigger's secret, kept as a repository secret. The posted text is placed after the saved prompt as the event.

Send an `Idempotency-Key` header to the trigger's URL, set to the workflow run id, so a re-run of the failed job starts nothing new. If several repositories share the same base image they tend to break in the same hour, so set the automation's max runs per hour with that in mind. An event past the cap waits as a `queued` run until the hour has room.

## Why run it on Rush?

Whether you see this error depends on when your environment was created. A laptop virtualenv built two years ago still holds an old MarkupSafe and imports cleanly, which is why the usual first reply to this bug report is that it works locally. The run installs from the repository's files into an empty environment in its own sandbox, so it sees what your image build sees, and the session transcript keeps each install command with the versions it resolved.

The three candidate fixes are also cheap to state and tedious to compare. Each needs its own environment, an interpreter the pins accept, and the same check run against it. The agent does all three and brings back the one failure that matters for planning: upgrading Jinja2 on its own trades this ImportError for another one in Flask.

## Frequently asked questions

### Why did this start failing when nothing in my repository changed?

One requirement in the chain has no upper bound, so every fresh install takes the newest MarkupSafe. Jinja2 2.x imports `soft_unicode`, and MarkupSafe removed that name in 2.1.0. Any environment created after that release resolves a version without it. Existing environments keep working until they are rebuilt.

### Is pinning MarkupSafe to 2.0.1 a real fix or a workaround?

It is a correct statement of what Jinja2 2.x needs, so it belongs in the file either way. It is also a ceiling: 2.0.1 has no wheels past CPython 3.10. The agent applies the cap to restore the install and reports the upgrade path separately, so the cap does not become permanent by default.

### Can I just upgrade Jinja2?

Only if Flask moves with it. Flask 1.x imports `Markup` and `escape` from Jinja2, and Jinja2 3.1 dropped both, so the app fails with a different ImportError. The agent tests that combination and shows the traceback so the pull request does not suggest it.

### My project has a lock file. Does this still apply?

A lock file that pins MarkupSafe protects installs made from it. The error then appears in the paths that bypass the lock: a Dockerfile that installs from `requirements.in`, a `pip install .` of the package, or a CI job that upgrades everything. The agent reads each install command it can find and reports which ones use the lock.

### Will the agent start my application?

It imports it and calls it through Flask's test client. It does not bind a port, open a browser window or start a GUI toolkit. For a desktop wrapper like this one the pull request says that the window was not exercised.

## More jobs like this: Fix a bug from an alert

- [Fix "AttributeError: module 'matplotlib.cm' has no attribute 'get_cmap'" on Matplotlib 3.9](https://getrush.ai/run/fix-matplotlib-cm-get-cmap-attribute-error/matplotlib/)
- [Fix "TypeError: Missing parameter name at 1" After Upgrading to Express 5](https://getrush.ai/run/fix-missing-parameter-name-at-1/path-to-regexp/)
- [Fix "AttributeError: module 'bcrypt' has no attribute '__about__'" with passlib](https://getrush.ai/run/fix-module-bcrypt-has-no-attribute-about/passlib/)
- [Fix "AttributeError: module 'cv2' has no attribute 'xfeatures2d'" by Moving SIFT to cv2.SIFT_create](https://getrush.ai/run/fix-module-cv2-has-no-attribute-xfeatures2d/opencv-python/)
- [Fix "AttributeError: module 'emoji' has no attribute 'UNICODE_EMOJI'"](https://getrush.ai/run/fix-module-emoji-has-no-attribute-unicode-emoji/emoji/)
- [Fix Moment's "Value Provided Is Not in a Recognized RFC2822 or ISO Format" Warning](https://getrush.ai/run/fix-moment-value-provided-is-not-in-a-recognized-format-warning/moment/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
