{"id":4417,"library":"algoliasearch-django","title":"Algolia Search integration for Django","description":"This package provides seamless integration of the Algolia Search API into Django projects. It is currently at version 4.0.0 and is actively maintained, with a focus on compatibility with modern Python and Django versions, built upon the `algoliasearch-client-python` library.","status":"active","version":"4.0.0","language":"python","source_language":"en","source_url":"https://github.com/algolia/algoliasearch-django","tags":["django","algolia","search","full-text-search","api-integration"],"install":[{"cmd":"pip install algoliasearch-django","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core framework dependency, requires Django>=4.0 for algoliasearch-django v4.","package":"Django","optional":false},{"reason":"Underlying Algolia Python API client, requires algoliasearch>=4.0,<5.0.","package":"algoliasearch","optional":false}],"imports":[{"note":"The official documentation and recent examples consistently use 'import algoliasearch_django as algoliasearch' for the module that exposes `register`.","wrong":"from django.contrib import algoliasearch","symbol":"algoliasearch","correct":"import algoliasearch_django as algoliasearch"},{"symbol":"AlgoliaIndex","correct":"from algoliasearch_django import AlgoliaIndex"},{"symbol":"register (decorator)","correct":"from algoliasearch_django.decorators import register"}],"quickstart":{"code":"import os\nimport django\nfrom django.conf import settings\nfrom django.db import models\n\n# Configure Django settings minimally for standalone execution\nif not settings.configured:\n    settings.configure(\n        INSTALLED_APPS=[\n            'django.contrib.auth',\n            'django.contrib.contenttypes',\n            'myapp',\n            'algoliasearch_django'\n        ],\n        DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}},\n        ALGOLIA={\n            'APPLICATION_ID': os.environ.get('ALGOLIA_APPLICATION_ID', 'YOUR_APP_ID'),\n            'API_KEY': os.environ.get('ALGOLIA_API_KEY', 'YOUR_API_KEY'),\n            'INDEX_PREFIX': 'dev_',\n        },\n        DEFAULT_AUTO_FIELD='django.db.models.AutoField',\n        SECRET_KEY='a-very-secret-key',\n        DEBUG=True\n    )\ndjango.setup()\n\n# models.py (example in a fictional 'myapp')\nclass Product(models.Model):\n    name = models.CharField(max_length=255)\n    description = models.TextField()\n    price = models.DecimalField(max_digits=10, decimal_places=2)\n    created_at = models.DateTimeField(auto_now_add=True)\n\n    def __str__(self):\n        return self.name\n\n    class Meta:\n        app_label = 'myapp'\n\n# index.py (example in 'myapp')\nfrom algoliasearch_django import AlgoliaIndex\nfrom algoliasearch_django.decorators import register\n\n@register(Product)\nclass ProductIndex(AlgoliaIndex):\n    fields = ('name', 'description', 'price', 'created_at')\n    settings = {'searchableAttributes': ['name', 'description'], 'attributesForFaceting': ['price']}\n    # You can customize `get_attribute_name` or `get_extra_attributes` for more complex indexing\n\n# --- Example Usage (after defining models and index, typically run via manage.py) ---\n\n# This part would typically be run via `python manage.py shell` or a management command.\n# For demonstration, we simulate creating and saving an object.\n# In a real Django app, signals handle auto-indexing on save.\n\n# Create a product (this would automatically index if AUTO_INDEXING is True, which is default)\n# from myapp.models import Product\n# p1 = Product.objects.create(name=\"Wireless Headphones\", description=\"High-quality audio experience.\", price=199.99)\n# p2 = Product.objects.create(name=\"Bluetooth Speaker\", description=\"Portable and powerful sound.\", price=79.99)\n# print(\"Products created and indexed.\")\n\n# To manually reindex all: python manage.py algolia_reindex\n# To apply settings: python manage.py algolia_applysettings\n\nprint(\"Algolia Django integration configured. To index data, run 'python manage.py algolia_reindex' or save model instances.\")\n","lang":"python","description":"To get started, first configure your Algolia credentials in your Django `settings.py` under an `ALGOLIA` dictionary. Then, define your Django models. Finally, create an `index.py` file within your app and register your models for indexing using either `algoliasearch.register()` or the `@register` decorator with a subclass of `AlgoliaIndex` to specify index settings and fields. Remember to add `algoliasearch_django` to your `INSTALLED_APPS`."},"warnings":[{"fix":"Upgrade Python to 3.8+ and Django to 4.0+. Refer to Django's own upgrade guides for framework-specific changes.","message":"Version 4.0.0 drops support for Python versions older than 3.8 and Django versions older than 4.0. Ensure your project meets these minimum requirements before upgrading.","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Replace all calls to `algoliasearch.clear_index(Model)` with `algoliasearch.clear_objects(Model)`.","message":"The `clear_index` method has been removed in favor of `clear_objects` for improved clarity and consistency with the underlying Algolia API client.","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Update your `settings.py` to use `ALGOLIA = {'APPLICATION_ID': 'YOUR_APP_ID', 'API_KEY': 'YOUR_API_KEY'}`.","message":"The configuration for Algolia in `settings.py` has changed. Instead of `ALGOLIA_APPLICATION_ID` and `ALGOLIA_API_KEY` as top-level settings, they are now nested within a single `ALGOLIA` dictionary.","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Distinguish between 'API_KEY' (Admin) for backend operations and 'SEARCH_API_KEY' (Search-Only) for frontend search queries.","message":"When performing searches from the frontend, use the dedicated 'Search-Only API Key' rather than the 'Admin API Key'. The Admin API Key has full write access and should never be exposed client-side.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully select which fields to index using the `fields` attribute in `AlgoliaIndex`. Consider using `get_extra_attributes` or `get_raw_record` to preprocess and limit the data sent to Algolia, only indexing data relevant for search.","message":"Records exceeding Algolia's size limit (typically 10KB) will cause indexing errors. This often occurs when indexing too many fields or large related objects.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that related objects are correctly handled, potentially by overriding `save_record` or using custom signals to trigger updates to the main model's index entry when M2M relationships change. Manual re-indexing (`python manage.py algolia_reindex`) might be necessary in some cases.","message":"Issues can arise with Many-to-Many relationships not updating correctly in the Algolia index, particularly on model saves. Sometimes manual re-indexing is required.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-22T07:58:51.061Z","next_check":"2026-07-11T00:00:00.000Z","problems":[{"fix":"Install the package using 'pip install --upgrade \"algoliasearch-django>=4.0,<5.0\"'.","cause":"The 'algoliasearch-django' package is not installed or not properly added to the Python environment.","error":"ModuleNotFoundError: No module named 'algoliasearch_django'"},{"fix":"Replace 'clear_index' with 'clear_objects' in your code.","cause":"The 'clear_index' method has been deprecated and removed in version 4.0.0 of 'algoliasearch-django'.","error":"ImportError: cannot import name 'clear_index' from 'algoliasearch_django'"},{"fix":"Upgrade 'algoliasearch-django' to a compatible version using 'pip install --upgrade \"algoliasearch-django>=4.0,<5.0\"'.","cause":"Version 1.7.1 of 'algoliasearch-django' is incompatible with 'algoliasearch' version 2.0.4.","error":"ERROR: algoliasearch-django 1.7.1 has requirement algoliasearch<2.0,>=1.0, but you'll have algoliasearch 2.0.4 which is incompatible."},{"fix":"Upgrade 'urllib3' and 'requests' packages using 'pip install --upgrade urllib3 requests'.","cause":"An incompatibility between 'urllib3' and 'requests' versions causes this error during the 'algolia_reindex' command.","error":"TypeError: float() argument must be a string or a number, not 'tuple'"},{"fix":"Import 'register' using 'from algoliasearch_django.decorators import register'.","cause":"The 'register' function is not directly available in 'algoliasearch_django' and should be imported from 'algoliasearch_django.decorators'.","error":"AttributeError: module 'algoliasearch_django' has no attribute 'register'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.0.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://www.algolia.com","github":"https://github.com/algolia/algoliasearch-django","docs":null,"changelog":null,"pypi":"https://pypi.org/project/algoliasearch-django/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","http-networking","database"],"base_url":null,"auth_type":null,"install_checks":{"last_tested":"2026-05-22","tag":null,"tag_description":null,"installed_version":"4.0.0","pypi_latest":"4.0.0","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"algoliasearch-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"66.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"algoliasearch-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":3.5,"import_time_s":null,"mem_mb":null,"disk_size":"67M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"algoliasearch-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"70.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"algoliasearch-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":3.4,"import_time_s":null,"mem_mb":null,"disk_size":"71M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"algoliasearch-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"62.4M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"algoliasearch-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":3.3,"import_time_s":null,"mem_mb":null,"disk_size":"63M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"algoliasearch-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"62.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"algoliasearch-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":3.4,"import_time_s":null,"mem_mb":null,"disk_size":"63M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"algoliasearch-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"64.4M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"algoliasearch-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":3.8,"import_time_s":null,"mem_mb":null,"disk_size":"65M"}]},"_links":{"self":"https://checklist.day/api/registry/algoliasearch-django","v1":"https://checklist.day/v1/registry/algoliasearch-django","v1_install":"https://checklist.day/v1/registry/algoliasearch-django/install","v1_imports":"https://checklist.day/v1/registry/algoliasearch-django/imports","v1_compatibility":"https://checklist.day/v1/registry/algoliasearch-django/compatibility","v1_quickstart":"https://checklist.day/v1/registry/algoliasearch-django/quickstart","docs":"https://checklist.day/docs"}}