{"id":8950,"library":"django-haystack","title":"Django Haystack","description":"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.","status":"active","version":"3.3.0","language":"python","source_language":"en","source_url":"https://github.com/django-haystack/django-haystack","tags":["django","search","full-text-search","solr","elasticsearch","whoosh","orm-integration"],"install":[{"cmd":"pip install django-haystack","lang":"bash","label":"Base installation"},{"cmd":"pip install 'django-haystack[whoosh]'","lang":"bash","label":"For Whoosh backend"},{"cmd":"pip install 'django-haystack[elasticsearch]' # or [elasticsearch5], [elasticsearch6], [elasticsearch7]","lang":"bash","label":"For Elasticsearch backend"},{"cmd":"pip install 'django-haystack[solr]'","lang":"bash","label":"For Solr backend"}],"dependencies":[{"reason":"Required for the Whoosh search backend","package":"whoosh","optional":true},{"reason":"Required for the Solr search backend","package":"pysolr","optional":true},{"reason":"Required for Elasticsearch search backends","package":"elasticsearch","optional":true}],"imports":[{"wrong":"from haystack.query import SearchQuerySet","symbol":"SearchQuerySet","correct":"from haystack.query import SearchQuerySet"}],"quickstart":{"code":"import os\nfrom django.conf import settings\n\n# Minimal Django settings configuration required for Haystack's imports\n# and internal mechanisms to initialize.\nif not settings.configured:\n    settings.configure(\n        INSTALLED_APPS=[\n            'haystack',\n            # 'your_app_with_models_and_search_indexes', # Add your app here in a real project\n        ],\n        BASE_DIR=os.path.dirname(os.path.abspath(__file__)),\n        HAYSTACK_CONNECTIONS={\n            'default': {\n                'ENGINE': 'haystack.backends.whoosh_backend.WhooshEngine',\n                'PATH': os.path.join(os.path.dirname(os.path.abspath(__file__)), 'whoosh_index'),\n            }\n        },\n        SECRET_KEY=os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-for-demo'),\n        DEBUG=True,\n        TIME_ZONE='UTC',\n        USE_TZ=True,\n        DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}}\n    )\n\n# Haystack requires Django apps to be ready to correctly discover indexes\nimport django\ndjango.setup()\n\n# Now we can import SearchQuerySet\nfrom haystack.query import SearchQuerySet\n\n# IMPORTANT: In a real Django project, before this code yields results, you would need:\n# 1. A Django model (e.g., `myapp/models.py`)\n# 2. A Haystack SearchIndex for your model (e.g., `myapp/search_indexes.py`)\n# 3. Your app added to INSTALLED_APPS in settings.py\n# 4. You would have run `./manage.py rebuild_index` to populate the search index.\n\nprint(\"Attempting to perform a search query (requires a populated index to show results)...\\n\")\n\ntry:\n    # Example 1: Filtering search results\n    # Assumes your SearchIndex has 'content' and 'pub_date' fields.\n    results = SearchQuerySet().filter(content='example').order_by('-pub_date')\n\n    if results:\n        print(f\"Found {len(results)} results for 'example':\")\n        for result in results:\n            # result.object would give you the actual Django model instance in a real project\n            print(f\"  Title: {getattr(result, 'title', 'N/A')}, Content: {getattr(result, 'content', 'N/A')}, Model: {result.model_name}\")\n    else:\n        print(\"No results found for 'example'. (Requires a populated search index.)\")\n\n    # Example 2: Auto-query (searches across the default 'text' field)\n    more_results = SearchQuerySet().auto_query('another note').models('Note').load_all()\n    print(f\"\\nFound {len(more_results)} results for 'another note' in 'Note' model (auto_query):\")\n    for result in more_results:\n        print(f\"  Title: {getattr(result, 'title', 'N/A')}\")\n\nexcept Exception as e:\n    print(f\"An error occurred during search: {e}\")\n    print(\"\\nTroubleshooting: \")\n    print(\"1. Ensure you have installed a specific search backend, e.g., `pip install 'django-haystack[whoosh]'`\")\n    print(\"2. Ensure you have run `./manage.py rebuild_index` in your Django project to populate the index.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your project to Python 3.","message":"Haystack 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.","severity":"breaking","affected_versions":"<3.0"},{"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+).","message":"Haystack v2.8.0 dropped support for Django 1.8. Later versions of Haystack only support Django 1.11 and newer.","severity":"breaking","affected_versions":"<2.8.0"},{"fix":"Upgrade `django-haystack` to version 3.3.0 or later when using Django 3, 4, or 5.","message":"Haystack 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.","severity":"breaking","affected_versions":"<3.3.0"},{"fix":"Install `django-haystack` with the appropriate extras, e.g., `pip install 'django-haystack[whoosh]'` or `pip install 'django-haystack[elasticsearch]'`.","message":"Installing `django-haystack` alone does not install the required dependencies for specific search backends (e.g., Whoosh, Solr, Elasticsearch).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Execute `python manage.py rebuild_index` on your Django project after defining your models and `SearchIndex` classes.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'-3.12':48 '3':35 '3.3.0':29 '3.8':47 '4':37 '5':40 'api':16 'applic':12 'backend':20 'compat':44,57 'django':1,3,11,34,55,58 'driven':52 'elasticsearch':23,65 'full':61 'full-text-search':60 'haystack':2,4 'integr':69 'latest':27 'like':21 'new':54 'offer':30 'offici':31 'orm':68 'orm-integr':67 'pluggabl':7 'primarili':51 'provid':13 'python':46 'releas':49 'search':8,19,59,63 'solr':22,64 'solut':9 'support':32 'text':62 'unifi':15 'various':18 'version':28,56 'whoosh':25,66 'x':36,38,41","created_at":"2026-04-16T18:47:41.937696+00:00","updated_at":"2026-04-16T18:47:41.937696+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\n  File \"/tmp/tmppmi_qe1f/venv/lib/python3.12/site-packages/haystack/__init__.py\", line 7, in <module>\n    from haystack.constants import DEFAULT_ALIAS\n  File \"/tmp/tmppmi_qe1f/venv/lib/python3.12/site-packages/haystack/constan"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.4.0","cli_name":"","cli_version":null,"type":"library","homepage":"http://haystacksearch.org/","github":"https://github.com/django-haystack/django-haystack","docs":"https://django-haystack.readthedocs.io","changelog":null,"pypi":"https://pypi.org/project/django-haystack/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","database","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}