iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
If your Python 3.13 traceback points to cgi.escape in legacy Whoosh, the likely cause is that Python 3.13 removed the standard-library cgi module. A possible one-line local workaround is to change import cgi to import html as cgi in Whoosh’s compat.py—but only after checking that the installed code uses cgi for escaping alone. This is an inferred workaround, not a verified upstream patch. For a longer-term fix, consider replacing legacy Whoosh with whoosh3 if your project’s dependencies allow it.
First confirm that legacy Whoosh is the failure point
Python 3.13 removed cgi, as documented in the Python 3.13 deprecations. A third-party Whoosh integration guide identifies Whoosh==2.7.4 as using cgi.escape in whoosh/compat.py. That makes this legacy Whoosh code path a plausible cause when the traceback names cgi or cgi.escape; it does not mean every django-haystack installation fails on Python 3.13.
- Capture the full traceback and note the first failing file and line. A failure in
whoosh/compat.pyinvolvingcgiis consistent with the reported issue. - Record the installed Python, Django, django-haystack, and Whoosh distribution versions. The compatibility of one package does not establish compatibility of the full stack.
- Inspect the installed
whoosh/compat.pyand confirm whether it importscgito usecgi.escape. Do not edit based only on the Python version.
When the one-line workaround is appropriate
If the installed file imports cgi only to call its escaping function, replacing the import with import html as cgi may preserve the existing cgi.escape reference while using Python’s HTML escaping module. This is an inference from the code path, not a patch confirmed by an upstream Whoosh issue or release note. Review every use of cgi in that file first; the alias is not a general replacement for the removed module.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsA direct edit inside an installed package is fragile: reinstalling or upgrading the dependency can overwrite it, and the change may be difficult to reproduce across developer machines and deployment environments. If you use it temporarily, record the change in your project’s deployment process and run the tests described below before shipping.
#1 Best Overall
Prefer a package change when your dependency constraints allow it
The Whoosh integration guide describes whoosh3 as an alternative that retains the public modules used by Haystack and supports Python 3.10–3.14, according to that guide. It also reports an end-to-end index, update, and search run with django-haystack 3.4.0, whoosh3 3.43.0, Django 6.1, and Python 3.12. That example is not a direct verification of the same stack on Python 3.13, so check your own version combination.
Whoosh and whoosh3 both provide the top-level whoosh import. The guide warns that the distributions conflict: remove legacy Whoosh rather than installing both. Review your dependency lockfile and deployment environment so that only the intended distribution supplies that import.
Check the whole Python, Django, and Haystack combination
The failure may be in Whoosh even when Django and django-haystack themselves support your interpreter. Django’s official Python 3.13 compatibility ticket identifies Django 5.1 as the first Django version supporting Python 3.13. That says nothing by itself about a third-party search backend.
django-haystack’s release history distinguishes its version support and testing history: v3.3 listed Django 3–5 and Python 3.8–3.12 as supported, while v3.4 added Python 3.13 to its test matrix. A Python version in the project’s test matrix does not guarantee every Haystack, Django, and backend combination. Check the release notes for the exact Haystack version you have installed.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Verify indexing and search before deployment
After changing a dependency or applying a local patch, test the operations your application relies on—not just whether Django starts or imports Haystack.
- Run the project’s test suite in the target Python environment.
- Create or open the search index, then index a representative document.
- Execute a query that should find that document and check the returned result.
- Exercise related Django integrations and deployment steps that use the search backend.
- Confirm the same dependency set is installed in CI and production, with no simultaneous Whoosh and whoosh3 distributions.
The cited integration guide provides a Python 3.12 example, not a verified Python 3.13 end-to-end run for your application. Treat the smoke test as necessary validation of your own stack.
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.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →
