Install & Compatibility
Where this runs
tested against v4.45.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.282s · 52MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.3s · import 2.082s · 53MB
52MB installed
● package 52MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SearchClient
✓ from algoliasearch.search.client import SearchClient
✗ from algoliasearch import algoliasearch
The `algoliasearch.Client` and direct `algoliasearch` module import patterns were used in older major versions (v1/v2). For v3 and v4, `SearchClient` from `algoliasearch.search.client` is the correct entry point.
This quickstart demonstrates how to initialize the Algolia client, initialize an index, add a new object, search for objects, and update an object. Remember to replace placeholder API keys and application IDs with your actual credentials, ideally fetched from environment variables. For indexing operations, always use your Admin API Key.
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}")
Debug
Known issues
breakingMajor 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.fixReview 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.
affects: >=4.0.0
breakingBreaking 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.fixAlways 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.
affects: >=4.35.3, >=4.36.0
gotchaUsing the Search-Only API Key for indexing or administrative operations will result in permission errors. These operations require an Admin API Key.fixEnsure 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`).
affects: All v4 versions
gotchaUsers 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.fixConfigure 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.
affects: All v4 versions
gotchaVersion 4.31.0 introduced a potentially breaking `urllib3` dependency constraint that could conflict with other packages in your environment.fixIf 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.
affects: 4.31.0
Upgrade
Version history
4.45.0latest on PyPI · released Aug 18, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.8.1 or newer.