If a django-haystack project fails under Python 3.13 with an error involving cgi or cgi.escape, check whether it uses legacy Whoosh 2.7.4. Python 3.13 removed the standard-library cgi module, and a Whoosh integration guide identifies that legacy code path as a likely cause. The commonly suggested one-line edit—import html as cgi—is an inferred local workaround, not a verified or upstream-supported patch. Inspect the installed file before applying it; replacing legacy Whoosh with whoosh3 may be a cleaner option if your dependency constraints allow it.
Why this error can appear on Python 3.13
Python 3.13 removed the standard-library cgi module. The Whoosh 3 integration guide points to legacy Whoosh==2.7.4 code in whoosh/compat.py that calls cgi.escape. If that is the code in your environment, the missing module can explain an import or runtime failure. The Python deprecation documentation describes the removal: Python 3.13 deprecations.
As an Amazon Associate I earn from qualifying purchases.
This is a dependency-specific diagnosis, not evidence that django-haystack itself universally fails on Python 3.13. A traceback mentioning cgi is a clue; confirm the package and code path rather than assuming every Haystack/Whoosh installation has the same problem.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Check your exact versions and the failing code
- Capture the full traceback. Note the first failing import or call and whether it points into
whoosh/compat.py. - Record the environment. Check the Python, Django, django-haystack, and Whoosh distribution versions used by the failing environment.
- Inspect the installed module. Confirm that the installed package is legacy Whoosh and that its
whoosh/compat.pyimportscgito usecgi.escape. Do not edit a different code path based only on a matching error message.
Compatibility depends on the whole stack. django-haystack v3.3 listed Django 3–5 and Python 3.8–3.12 as supported; its v3.4 changelog added Python 3.13 to the test matrix. A test-matrix entry is not a guarantee for every Django version or search backend combination. Review the project’s release history for the version you have installed.
#1 Best Overall
Django’s official compatibility tracking identifies Django 5.1 as the first Django version supporting Python 3.13. That establishes Django compatibility, not compatibility of a third-party search dependency. See Django ticket #34900.
Option 1: Replace legacy Whoosh with whoosh3
If your project can accommodate a dependency change, the integration guide documents whoosh3 as an alternative that retains the public modules used by Haystack and supports Python 3.10–3.14. The guide’s end-to-end example used django-haystack 3.4.0, whoosh3 3.43.0, Django 6.1, and Python 3.12. That example does not directly verify the same stack on Python 3.13, so test your own combination before relying on it.
Whoosh and whoosh3 both provide the top-level whoosh import, so the guide warns against installing both distributions together. Remove legacy Whoosh before installing its replacement, and check your lockfile and deployment environment to ensure the old distribution is not reintroduced.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsOption 2: Apply the inferred one-line compatibility edit
If you need a temporary local workaround and inspection confirms that the affected code uses cgi only for its escape API, replacing its import with import html as cgi may preserve the existing name while routing calls to Python’s HTML escaping module. This is an inference from the reported code path, not a patch verified by an authoritative Whoosh or django-haystack issue or release note. The guide documents the underlying problem; it does not establish this particular edit as supported or tested.
Before changing the file, review every import and use of cgi in that module. If the code depends on anything beyond the escaping function, the alias may not be sufficient. Also remember that a direct edit inside an installed package can disappear when the package is reinstalled or upgraded. If you use this workaround, track it explicitly and plan to remove it when you move to a maintained compatible dependency path.
Choose the fix that fits your project
| Approach | What changes | Main consideration |
|---|---|---|
| Local compatibility edit | A change to the installed legacy module | Inferred workaround, not upstream-verified; inspect other cgi uses and maintain the patch yourself. |
| Replace Whoosh with whoosh3 | Dependency and environment configuration | The guide documents compatible public modules and a Python 3.10–3.14 support range, but its full-loop example used Python 3.12; do not install both distributions. |
| Change search backend | Backend configuration and potentially broader application or data changes | Whether the index can be reused or must be rebuilt is not established for every deployment; assess migration behavior for your exact stack. |
For any route, evaluate compatibility with your installed Haystack and Django versions, the maintenance status of the selected dependency, index and reindexing implications, and whether CI can exercise real indexing and querying. The available package information does not settle migration behavior for every application.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Verify the fix before deployment
Run the application’s test suite, then perform a smoke test that exercises the search lifecycle rather than stopping at a successful import:
- Create or open the index.
- Index a representative document.
- Run a query and confirm the expected document is returned.
- Run relevant tests for the application’s other Django integrations.
Repeat these checks in the same Python, Django, Haystack, and search-package combination you intend to deploy. A dependency change or local edit is not verified merely because the original traceback disappears.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
