Install & Compatibility
Where this runs
tested against v3.18.2 · 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.910 runs
installs and imports cleanly · install 0.0s · import 1.167s · 32.3MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.0s · import 1.076s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from marqo import Client
✗ from marqo import MarqoClient
The primary client class was renamed from `MarqoClient` to `Client` in Marqo v2.0.0. Using `MarqoClient` will result in an `ImportError` on newer versions.
This quickstart demonstrates how to initialize a Marqo client, create an index, add documents, and perform a basic search. It includes environment variable support for connecting to a Marqo instance and handles index creation idempotently.
import marqo
import os
# For local Marqo instances (e.g., via Docker), the URL is often http://localhost:8882
# For cloud instances, set MARQO_URL and optionally MARQO_API_KEY
marqo_url = os.environ.get('MARQO_URL', 'http://localhost:8882')
marqo_api_key = os.environ.get('MARQO_API_KEY', None)
mq = marqo.Client(url=marqo_url, api_key=marqo_api_key)
index_name = "my-first-marqo-index"
# Create an index (if it doesn't exist)
try:
mq.get_index(index_name=index_name)
print(f"Index '{index_name}' already exists.")
except marqo.errors.MarqoApiError as e:
if "index_not_found" in str(e).lower():
print(f"Creating index '{index_name}'...")
mq.create_index(index_name=index_name)
else:
raise e
# Add documents to the index
docs = [
{
"_id": "doc1",
"title": "The Art of Computer Programming",
"description": "A series of comprehensive monographs by Donald Knuth covering many topics in computer science."
},
{
"_id": "doc2",
"title": "Structure and Interpretation of Computer Programs",
"description": "An influential computer science textbook by Abelson and Sussman, known as SICP."
}
]
response_add = mq.add_documents(index_name=index_name, documents=docs)
print("Added documents:", response_add)
# Perform a search
search_query = "computer science textbooks"
response_search = mq.search(index_name=index_name, q=search_query)
print(f"\nSearch results for '{search_query}':")
for hit in response_search['hits']:
print(f" Title: {hit['title']}, Score: {hit['_score']:.2f}")
# Clean up (optional): delete the index
# mq.delete_index(index_name=index_name)
marqo --version
Errors
Common errors & fixes
urllib3.exceptions.MaxRetryError: HTTPConnectionPool(host='localhost', port=8882): Max retries exceeded with url: /indexes (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at ...>: Failed to establish a new connection: [Errno 111] Connection refused'))
The Marqo server (often a Docker container) is not running or is not accessible at the specified URL and port.
fixEnsure your Marqo Docker container is running (e.g., `docker ps` to check). Verify the `url` in `marqo.Client()` is correct, usually `http://localhost:8882` for local setups.
marqo.errors.MarqoApiError: Could not find index 'my-non-existent-index'
Attempted to access, add documents to, or search an index that has not been created or whose name is misspelled.
fixCheck the index name for typos. If the index should exist, ensure `mq.create_index(index_name='your-index-name')` was called successfully before attempting other operations.
marqo.errors.MarqoApiError: Invalid model_properties: key model_properties.model. If model_properties.model is not specified, you must either specify it through the `model` param, or use default settings.
This error typically occurs in Marqo v2.0.0+ when using an older index creation schema where `model` was a top-level parameter, instead of being nested under `model_properties`.
fixUpdate your `create_index` call to use the `model_properties` dictionary for specifying the model. Example: `mq.create_index(index_name, model_properties={'model': 'hf/e5-base'})`. Upgrade
Version history
3.18.2latest on PyPI · released May 13, 2026
Audit
Dependencies
No dependency data recorded yet.