Registry / web-framework / django-haystack

django-haystack

JSON →
library3.4.0pypypiunverified

Django Haystack is a pluggable search solution for Django applications, providing a unified API to various search backends like Solr, Elasticsearch, and Whoosh. The latest version, 3.3.0, offers official support for Django 3.x, 4.x, and 5.x, and is compatible with Python 3.8-3.12. Releases are primarily driven by new Django version compatibility.

pip install django-haystack
INSTALL
IMPORT
SIG · DJANGO-HAYSTACK
D
django-haystack
web-frameworkpythonv3.4.0
Install
5.8s avg
Import
—
Disk
67MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v3.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.960 runs
installs and imports cleanly · install 0.0s · import 0.000s · 68MB
glibc
py 3.10–3.960 runs
installs and imports cleanly · install 5.8s · import 0.000s · 69MB
67MB installed
● package 67MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SearchQuerySet
✓ from haystack.query import SearchQuerySet
✗ from haystack.query import SearchQuerySet

This quickstart demonstrates how to set up minimal Django settings for Haystack and perform basic search queries using `SearchQuerySet`. Note that for actual results, you need a full Django project with models, SearchIndexes defined, and the `python manage.py rebuild_index` command executed to populate the search index.

import os from django.conf import settings # Minimal Django settings configuration required for Haystack's imports # and internal mechanisms to initialize. if not settings.configured: settings.configure( INSTALLED_APPS=[ 'haystack', # 'your_app_with_models_and_search_indexes', # Add your app here in a real project ], BASE_DIR=os.path.dirname(os.path.abspath(__file__)), HAYSTACK_CONNECTIONS={ 'default': { 'ENGINE': 'haystack.backends.whoosh_backend.WhooshEngine', 'PATH': os.path.join(os.path.dirname(os.path.abspath(__file__)), 'whoosh_index'), } }, SECRET_KEY=os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-for-demo'), DEBUG=True, TIME_ZONE='UTC', USE_TZ=True, DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}} ) # Haystack requires Django apps to be ready to correctly discover indexes import django django.setup() # Now we can import SearchQuerySet from haystack.query import SearchQuerySet # IMPORTANT: In a real Django project, before this code yields results, you would need: # 1. A Django model (e.g., `myapp/models.py`) # 2. A Haystack SearchIndex for your model (e.g., `myapp/search_indexes.py`) # 3. Your app added to INSTALLED_APPS in settings.py # 4. You would have run `./manage.py rebuild_index` to populate the search index. print("Attempting to perform a search query (requires a populated index to show results)...\n") try: # Example 1: Filtering search results # Assumes your SearchIndex has 'content' and 'pub_date' fields. results = SearchQuerySet().filter(content='example').order_by('-pub_date') if results: print(f"Found {len(results)} results for 'example':") for result in results: # result.object would give you the actual Django model instance in a real project print(f" Title: {getattr(result, 'title', 'N/A')}, Content: {getattr(result, 'content', 'N/A')}, Model: {result.model_name}") else: print("No results found for 'example'. (Requires a populated search index.)") # Example 2: Auto-query (searches across the default 'text' field) more_results = SearchQuerySet().auto_query('another note').models('Note').load_all() print(f"\nFound {len(more_results)} results for 'another note' in 'Note' model (auto_query):") for result in more_results: print(f" Title: {getattr(result, 'title', 'N/A')}") except Exception as e: print(f"An error occurred during search: {e}") print("\nTroubleshooting: ") print("1. Ensure you have installed a specific search backend, e.g., `pip install 'django-haystack[whoosh]'`") print("2. Ensure you have run `./manage.py rebuild_index` in your Django project to populate the index.")
Debug
Known issues
breakingHaystack v3.0 dropped support for Python 2. Projects on Python 2 must use an older Haystack version (pre-3.0) or upgrade to Python 3.
fix
Upgrade your project to Python 3.
affects: <3.0
breakingHaystack v2.8.0 dropped support for Django 1.8. Later versions of Haystack only support Django 1.11 and newer.
fix
Upgrade your Django project to version 1.11 or higher (Django 2.0+ for Haystack 2.8.0+, Django 3.x+ for Haystack 3.x+).
affects: <2.8.0
breakingHaystack v3.3.0 adds official support for Django 3, 4, and 5. Older Haystack versions may not function correctly with these newer Django versions, especially around internal API changes.
fix
Upgrade `django-haystack` to version 3.3.0 or later when using Django 3, 4, or 5.
affects: <3.3.0
gotchaInstalling `django-haystack` alone does not install the required dependencies for specific search backends (e.g., Whoosh, Solr, Elasticsearch).
fix
Install `django-haystack` with the appropriate extras, e.g., `pip install 'django-haystack[whoosh]'` or `pip install 'django-haystack[elasticsearch]'`.
affects: All versions
gotchaWhen setting up a new Haystack index, you must run `python manage.py rebuild_index` (or `update_index`) to populate the search index with your existing data. Searches will return empty until this is done.
fix
Execute `python manage.py rebuild_index` on your Django project after defining your models and `SearchIndex` classes.
affects: All versions
Upgrade
Version history
3.4.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
whooshoptionalRequired for the Whoosh search backend
pysolroptionalRequired for the Solr search backend
elasticsearchoptionalRequired for Elasticsearch search backends
Agent activity
16 hits · last 30 days
node
12
Resources
django-haystack — pip install django-haystack · libregistry