{"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":"en","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-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}