Algolia Python API Client
raw JSON → 4.38.0 verified Wed May 13 auth: no python
The `algoliasearch` library is a fully-featured and blazing-fast Python API client designed to interact with the Algolia Search API. It provides a Pythonic interface to index data, configure search settings, perform queries, and access advanced features like analytics and recommendations. The library is actively maintained with frequent minor releases, currently at version 4.38.0.
pip install --upgrade 'algoliasearch>=4.0,<5.0' Common errors
error ModuleNotFoundError: No module named 'algoliasearch' ↓
cause The 'algoliasearch' package is not installed in the Python environment.
fix
Install the package using pip: 'pip install algoliasearch'.
error ImportError: cannot import name 'SearchClient' from 'algoliasearch' ↓
cause Attempting to import 'SearchClient' from 'algoliasearch' directly, which is incorrect.
fix
Use the correct import statement: 'from algoliasearch.search_client import SearchClient'.
error ValueError: Timeout value connect was (1, 30), but it must be an int or float. ↓
cause An incompatibility between 'urllib3' and 'requests' versions causes this error.
fix
Upgrade 'urllib3' and 'requests' to compatible versions: 'pip install --upgrade urllib3 requests'.
error AttributeError: module 'algoliasearch' has no attribute 'search_client' ↓
cause Using an outdated version of the 'algoliasearch' package that doesn't include 'search_client'.
fix
Upgrade to the latest version of 'algoliasearch': 'pip install --upgrade algoliasearch'.
error ModuleNotFoundError: No module named 'algoliasearch.search_client' ↓
cause This error typically occurs when the import path for the Algolia client has changed between major versions (e.g., from v1/v2 to v3/v4) or due to an incorrect installation/environment setup.
fix
Ensure you have the correct version of the library installed for your code, and update the import statement. For
algoliasearch v4+, the main client is imported from algoliasearch.search.client.
from algoliasearch.search.client import SearchClient Warnings
breaking Major breaking changes occurred when upgrading from `algoliasearch` v3 to v4. The client initialization method changed significantly from `algoliasearch.client.Client` to `algoliasearch.search.client.SearchClient.create`. Many method signatures were also updated to accept optional arguments via a `request_options` dictionary, instead of individual parameters. ↓
fix Review the official upgrade guide for Python API Client v4. Update client initialization and method calls according to the new `SearchClient` patterns and `request_options` usage.
breaking Breaking changes related to API schema fixes are introduced in minor versions. For instance, v4.36.0 included changes to `conditions` in composition rules, and v4.35.3 removed field requirements from the Composition API's run response. These can impact client types and expected data structures. ↓
fix Always check the release notes and changelog for each minor version update, especially for mentions of 'BREAKING CHANGES' related to API schema or model updates. Adapt your code to the updated data structures or API parameter requirements.
gotcha Using the Search-Only API Key for indexing or administrative operations will result in permission errors. These operations require an Admin API Key. ↓
fix Ensure you are using your Algolia Admin API Key (not the Search-Only API Key) when performing operations like `save_object`, `delete_object`, or modifying index settings. The Search-Only API Key should only be used for read operations (e.g., `search`).
gotcha Users behind corporate firewalls or with strict network configurations might encounter 'Unreachable hosts' errors. This usually indicates a timeout or connection issue preventing the client from reaching Algolia's servers. ↓
fix Configure connection timeouts for the Algolia client. You can create a `SearchConfig` object and pass it to `SearchClient.create_with_config()` to set `connect_timeout`, `read_timeout`, and `write_timeout` to appropriate values for your network environment. Consult your network administrator for allowed outbound connections.
gotcha Version 4.31.0 introduced a potentially breaking `urllib3` dependency constraint that could conflict with other packages in your environment. ↓
fix If experiencing `urllib3` dependency conflicts, consider pinning `algoliasearch` to a version immediately prior to 4.31.0 (e.g., `algoliasearch==4.30.0`) or explicitly pinning `urllib3` to a compatible version if other libraries permit it. Check your `pip freeze` output for `urllib3` conflicts.
Install compatibility last tested: 2026-05-13 v4.40.1 (up to date)
python os / libc status wheel install import disk mem side effects
3.10 alpine (musl) wheel - 2.24s 50.2M 29.2M clean
3.10 alpine (musl) - - 2.93s 50.3M 29.0M -
3.10 slim (glibc) wheel 8.2s 1.61s 51M 29.2M clean
3.10 slim (glibc) - - 2.00s 52M 29.0M -
3.11 alpine (musl) wheel - 2.98s 55.1M 30.9M clean
3.11 alpine (musl) - - 3.97s 55.3M 30.7M -
3.11 slim (glibc) wheel 6.5s 2.55s 57M 30.9M clean
3.11 slim (glibc) - - 3.27s 57M 30.7M -
3.12 alpine (musl) wheel - 2.54s 46.3M 30.5M clean
3.12 alpine (musl) - - 3.33s 46.5M 30.4M -
3.12 slim (glibc) wheel 5.2s 2.56s 48M 30.5M clean
3.12 slim (glibc) - - 3.85s 48M 30.4M -
3.13 alpine (musl) wheel - 2.41s 46.0M 31.1M clean
3.13 alpine (musl) - - 3.30s 46.1M 30.9M -
3.13 slim (glibc) wheel 5.5s 2.42s 47M 31.1M clean
3.13 slim (glibc) - - 3.28s 48M 30.9M -
3.9 alpine (musl) wheel - 2.07s 50.3M 29.4M clean
3.9 alpine (musl) - - 3.00s 50.2M 29.3M -
3.9 slim (glibc) wheel 9.2s 1.79s 52M 29.4M clean
3.9 slim (glibc) - - 2.16s 52M 29.3M -
Imports
- SearchClient wrong
from algoliasearch import algoliasearchcorrectfrom algoliasearch.search.client import SearchClient
Quickstart last tested: 2026-04-25
import os
from algoliasearch.search.client import SearchClient
# Initialize the client with your Application ID and API Key
# Ensure you use your Admin API Key for indexing operations, and Search-Only API Key for search.
APP_ID = os.environ.get('ALGOLIA_APP_ID', 'YOUR_ALGOLIA_APP_ID')
API_KEY = os.environ.get('ALGOLIA_API_KEY', 'YOUR_ALGOLIA_ADMIN_API_KEY') # Use Admin API Key for writes
INDEX_NAME = os.environ.get('ALGOLIA_INDEX_NAME', 'your_index_name')
if not APP_ID or not API_KEY:
print("Please set ALGOLIA_APP_ID and ALGOLIA_API_KEY environment variables or replace placeholders.")
else:
try:
client = SearchClient.create(APP_ID, API_KEY)
index = client.init_index(INDEX_NAME)
# Add a new record
record = {"objectID": "1", "name": "Algolia Search", "category": "Search Engines"}
save_response = index.save_object(record).wait()
print(f"Object saved: {save_response.object_ids[0]}")
# Search for records
search_results = index.search('Algolia', {
'attributesToRetrieve': ['name', 'category'],
'hitsPerPage': 1
})
print("\nSearch Results:")
for hit in search_results['hits']:
print(f"- Name: {hit['name']}, Category: {hit['category']}")
# Update an existing record
index.partial_update_object({"objectID": "1", "description": "Fast and relevant search."}).wait()
print("\nObject updated.")
# Delete a record (optional, uncomment to run)
# index.delete_object("1").wait()
# print("\nObject deleted.")
except Exception as e:
print(f"An error occurred: {e}")