How to Use Marqo: The Beginner's Guide (First Docker Run, First Index, the "Documents In" Lesson, First Search, and the Multimodal Arc)

CodexFuse Team · 2026-11-07T03:53:25.724Z · 17 min read min read

How Do I Use Marqo?

Learning how to use marqo takes seven moves: read the deprecation notice first, run the Docker container, install the Python client, create your first index, add documents, run your first search, and open the multimodal arc. Marqo is a tensor search engine that turns text and images into vectors and finds matches by meaning instead of keywords, so a plain-language question can find a document that shares no words with it. This marqo tutorial follows the official documentation, the project repository, and the package pages, with every fact checked as of November 2026.

Marqo's open-source engine is deprecated and will not receive updates, so this guide teaches the final release, 2.26.0, and says plainly where the old path still works and where it stops. CodexFuse offers no Marqo tool, so this guide teaches the real project on your own machine, not a web version of it. The deprecation changes the shape of the whole guide, because every step below is a legacy path, not a supported product.

The Qdrant beginner guide covers the vector database that most new projects pick today, and it is the pillar this page belongs to. This guide opens the tensor-search lane in the ai-search vector cluster, and it draws the line once against the bring-your-own-embeddings lane: Qdrant stores vectors you create yourself, while Marqo creates the vectors for you, so the two tools do different jobs in the same search stack.

1. Read the deprecation notice in the repository README before you install anything.
2. Run the Marqo Docker container on port 8882 with enough memory behind it.
3. Install the Python client and connect it to the running container.
4. Create your first index and pick the model at creation time.
5. Add documents and name the fields Marqo should turn into vectors.
6. Run your first search with a plain-language question.
7. Open the multimodal arc with a CLIP model and image documents.

Is Marqo Still Maintained?

No, the open-source Marqo engine is not maintained anymore. The project's own README carries a notice added on 13 November 2025 that says the open-source project is deprecated and will no longer receive updates, and the final release, 2.26.0, shipped on 7 April 2026, 214 days ago (7.0 months). The repository has not been archived, so the code stays public, but no new releases are coming.

The notice came 359 days ago, when the repository was 1,200 days old, and the final release followed 145 days after the notice. The last commit on the main branch landed on 10 April 2026, 211 days ago, and the last push to the repository was on 3 September 2026, 65 days ago. The company behind Marqo now sells an ecommerce search platform, and its docs and homepage cover only that commercial product.

The Git beginner guide covers cloning the repository so you can read that notice yourself before you install anything. A beginner in 2026 should treat Marqo as a learning project and a legacy system, not as a dependency for a new product. The rest of this guide still teaches the full arc, because the engine runs and the lessons transfer to every vector search tool.

What Is Marqo?

Marqo is an end-to-end tensor search engine for text and images that generates embeddings, stores them, and retrieves matches through a single API. Marqo tensor search turns documents into collections of vectors, then compares a query vector with the stored vectors to find the closest matches by meaning. You send documents in and get documents out, with no embedding pipeline to build yourself.

A keyword search matches words, while a tensor search matches meaning, so a query about the best outfit for the moon can find a spacesuit document that never uses the word outfit. The engine handles vector generation, storage, and retrieval out of the box, and it plugs in machine-learning models from PyTorch, Hugging Face, and OpenAI. That single-API promise is the whole pitch: three lines of code instead of a pipeline.

The project started on 1 August 2022, and the repository is 1,559 days old, or 4.27 years. It collected 5,025 stars and 241 forks, which is 20.85 stars per fork, and it still carries 196 open issues, or 3.9 open issues per 100 stars. Those numbers describe a popular project that stopped, not a small one that never grew.

The arithmetic behind those numbers is short, and it runs in Python from the fetched dates and counts.

repo_age_days = 1559
repo_age_years = round(repo_age_days / 365.25, 2)
days_since_release = 214
days_since_notice = 359
notice_to_release = 145
docker_tag_age = 601
docker_tag_older_than_release = docker_tag_age - days_since_release
stars = 5025
forks = 241
issues = 196
stars_per_fork = round(stars / forks, 2)
issues_per_100_stars = round(issues / stars * 100, 2)
release_months = round(days_since_release / 30.44, 1)
docker_tag_months = round(docker_tag_age / 30.44, 1)
print(repo_age_years)
print(stars_per_fork)
print(issues_per_100_stars)
print(notice_to_release)
print(docker_tag_older_than_release)
print(release_months)
print(docker_tag_months)

How Do I Install Marqo?

A marqo install starts with Docker, because the engine ships as a container and there is no other supported install route. Docker needs at least 8GB of memory and 50GB of storage, and the README warns that a container that keeps getting killed is almost always short of memory. Give Docker 8GB before you start, and the first run has a chance.

The Docker beginner guide covers installing Docker itself, and the VPS hosting guide covers the Linux server where most readers will run this container. The official run command pulls the image and maps port 8882, which is the port the client connects to. Run the three commands in order, and leave the terminal open while the container runs.

docker rm -f marqo
docker pull marqoai/marqo:latest
docker run --name marqo -it -p 8882:8882 marqoai/marqo:latest

A fuller variant of the same command adds two flags for networking and privileges. The variant below is the one the README shows for most machines, and Mac users with M-series chips follow a separate backend path in the same README.

docker run --name marqo -it --privileged -p 8882:8882 --add-host host.docker.internal:host-gateway marqoai/marqo:latest

The latest Docker image tag was last updated 601 days ago, or 19.7 months, so the documented pull command does not fetch the 2.26.0 release. The tag predates the final release by 387 days, and the newer cloud-latest tag was last updated 260 days ago, but no 2.26 release tag exists on Docker Hub at all. Treat the latest tag as a stale snapshot, and pin a version tag when you need a known build.

The M-series Mac guidance in this guide comes from the old README, which says the old backend is not supported on the arm64 architecture. M-series readers may need to run OpenSearch locally instead of using the single container. Check the README for your chip before you start, because this path is dated.

How Do I Connect the Python Client?

You connect to Marqo through the Python client, installed with one command. pip install marqo today installs the ecommerce-platform client, and the current version is 3.18.2, released on 13 May 2026, 178 days ago. The old tensor-search quickstart survives only in older package versions, such as 3.2.1, so a 2026 beginner meets a version split on the first step.

The client wraps the Marqo API in one object, and every later step in this guide runs through it. The connection points at the local container on port 8882, and the client is the only interface you need for the whole arc. Keep the container running in its own terminal, and run the client code in another.

pip install marqo

import marqo

mq = marqo.Client(url='http://localhost:8882')

Version 3.18.1 shipped one day before 3.18.2, which shows the client still moves while the engine stands still. That split is the most confusing thing about Marqo in 2026: the client version and the engine version no longer describe the same product. Match the client to the engine you run, not to the newest number.

How Do I Create My First Index?

You create your first index with one call that names the index and picks the model. The model choice is set at index creation, and it decides what the index can search, so pick it before you add documents. An index is a named collection of documents that share one model and one set of search settings.

The example below creates my-first-index with the hf/e5-base-v2 model, which is a text embedding model from Hugging Face. The 2.13.0 README names hf/all_datasets_v4_MiniLM-L6 as the default text model, and the default model for 2.26.0 was not verified, because the versioned docs now return 404. Use the example model when you follow along, and verify the default in the README for the release you run.

mq.create_index("my-first-index", model="hf/e5-base-v2")

The Ollama beginner guide covers running local models on your own machine, which is the same idea at a different layer: the model does the understanding, and the tool does the plumbing. Different models trade inference speed against relevancy, and the README says experimentation is often required. Start with the example model, measure, and change models only by creating a new index.

How Do I Add Documents to Marqo?

You add documents as a list of Python dictionaries, and Marqo embeds the fields you name for you. The documents in, documents out lesson is the whole product: you hand Marqo plain documents, and it turns the chosen fields into vectors without asking you to run a model. Name the searchable fields with tensor_fields, and Marqo indexes only those fields as vectors.

Each document can carry its own _id, and re-adding a document with the same _id updates it instead of duplicating it. Marqo generates an ID when you leave it out, so _id is optional but useful for updates. Add a few small documents first, and confirm they land before you index a whole collection.

mq.index("my-first-index").add_documents([
    {
        "Title": "The Travels of Marco Polo",
        "Description": "A 13th-century travelogue describing Polo's travels"
    },
    {
        "Title": "Extravehicular Mobility Unit (EMU)",
        "Description": "The EMU is a spacesuit that provides environmental protection, mobility, life support, and communications for astronauts",
        "_id": "article_591"
    }],
    tensor_fields=["Description"]
)

A document is a plain record with text fields, and the tensor fields are the ones Marqo makes searchable by meaning. Fields outside tensor_fields stay in the document but do not take part in vector search. That split is what makes one index hold both searchable text and plain metadata.

How Do I Run My First Search?

You run your first search by asking a plain-language question, and Marqo returns the closest documents first. The human-like-query lesson is that the question does not need to share words with the answer, because the match happens between vectors, not between keywords. Ask the question the way a person would ask it, and read the ranked hits.

Each hit carries a score, a highlight, and an ID, and the search returns 10 hits by default. A higher score means a closer match, and the highlights show which fields matched. Change the question when the top hit is wrong, because the query is the cheapest thing to change.

results = mq.index("my-first-index").search(
    q="What is the best outfit to wear on the moon?"
)

The same client also fetches single documents, runs keyword search, and deletes documents or whole indexes. The calls below are the basic operations from the README, and they all run against the same index you just built.

result = mq.index("my-first-index").get_document(document_id="article_591")

result = mq.index("my-first-index").search('marco polo', search_method=marqo.SearchMethods.LEXICAL)

results = mq.index("my-first-index").delete_documents(ids=["article_591", "article_602"])

results = mq.index("my-first-index").delete()

Keyword search still exists as a lexical option, and it matches words the old way when you need exact terms. Use tensor search for meaning and lexical search for exact names, codes, and part numbers. Most beginners need the tensor search first, and the lexical option second.

How Do I Search Text and Images Together?

A marqo multimodal search finds images with text and text with images, using one index for both. The index needs a CLIP model and the treat_urls_and_pointers_as_images setting, because image URLs are treated as plain strings unless you configure multimodal search. Set both at index creation, before you add any image documents.

The example below creates an index with the ViT-L/14 model, adds a document with an image URL and a description, and then searches it with a single word. A text query can find an image, and an image URL can find similar images, because both live in the same vector space. That cross-modal jump is the feature that made Marqo stand out.

response = mq.create_index("my-multimodal-index", model="ViT-L/14", treat_urls_and_pointers_as_images=True)

response = mq.index("my-multimodal-index").add_documents([{
    "My_Image": "https://raw.githubusercontent.com/marqo-ai/marqo-api-tests/mainline/assets/ai_hippo_realistic.png",
    "Description": "The hippopotamus, also called the common hippopotamus or river hippopotamus, is a large semiaquatic mammal native to sub-Saharan Africa",
    "_id": "hippo-facts"
}], tensor_fields=["My_Image"])

results = mq.index("my-multimodal-index").search('animal')

results = mq.index("my-multimodal-index").search('https://raw.githubusercontent.com/marqo-ai/marqo-api-tests/mainline/assets/ai_hippo_statue.png')

Weighted queries let you push a search toward one term and away from another, using a dictionary of terms and weights. Negative weights work as negation, so you can ask for one thing and exclude another in the same query. Keep the weights small at first, and watch the ranking move before you push harder.

Marqo vs Qdrant: Which One Fits Your Project?

Marqo vs Qdrant is the comparison most readers ask about, and the answer is that the two tools sit in different lanes. Qdrant is a vector database: you create the embeddings yourself and Qdrant stores, filters, and retrieves them. Marqo is a tensor search engine: it creates the embeddings for you, so you send documents in and get documents out.

Pick Qdrant when you want to control the embedding model, the pipeline, and the storage, and when you already have vectors. Pick Marqo when you want search without building an embedding pipeline, and when the documents-first workflow fits your app. A new project in 2026 should start with Qdrant, because Marqo's engine has a final release and no future ones.

Marqo Cloud or Self-Hosting: Which Path Is Still Open?

Marqo cloud is the commercial platform the company sells today, and self-hosting the old engine is the legacy path this guide teaches. Marqo Cloud needs an account and an ecommerce index, and its search runs through a REST API with an index header, not through the Python client. The old Docker path needs no account, but it runs a deprecated engine.

The company pivoted to AI ecommerce search and product discovery, and its homepage now pitches smarter search and higher conversion for shops. Its case-study percentages are Marqo's own marketing claims, and this guide repeats none of them as fact. This guide states no Marqo Cloud prices, because none were fetched for this article.

Choose Cloud when you run a shop and want the supported product, and choose the Docker engine only for learning or for a legacy system you already run. The docs site now covers only the commercial platform, and the old versioned docs return 404. Do not build a new product on an engine whose docs are gone.

Seven Mistakes Beginners Make With Marqo

Seven mistakes show up again and again, and each one has a cheap fix. Read the table before your first run, and most of these never happen to you.

The memory mistake stops the container before anything else runs, and the version mistake confuses the first step. Fix those two first, and the rest of the arc runs smoothly.

Sources

The GitHub API supplied the repository facts for this guide: 5,025 stars, 241 forks, 196 open issues, creation on 1 August 2022, the 2.26.0 release on 7 April 2026, and the deprecation notice added on 13 November 2025. The releases list supplied the eight recent versions, and the raw README supplied the notice wording and the first-run commands. The PyPI JSON API supplied the client versions, with 3.18.2 released on 13 May 2026, and the older PyPI pages supplied the surviving OSS quickstart text.

The Docker Hub tags API supplied the image dates, with latest last updated on 16 March 2025 and cloud-latest on 20 February 2026. The live docs site supplied the current Cloud search guide, and the live homepage supplied the ecommerce pivot, while the versioned OSS docs returned 404 on every check. DeepWiki's Marqo getting-started page carried the deprecation warning that this guide verified against the README.

The writer's own search checks this run found the same field the queue entry described: PyPI README mirrors, a DeepWiki reference, and the Cloud docs, with no unified independent beginner walkthrough and no tool page on page one. The Qdrant sibling article is live on CodexFuse, and the API slug probe returned 404 for this article before writing, with live controls at 200. No terminal outputs in this guide were executed in a live testbed, and no Facebook promotion applies to this article.

Frequently Asked Questions

Is Marqo free to use?

Yes, the open-source engine is free under the Apache-2.0 license, and the code stays public on GitHub. Marqo Cloud is the commercial product, and its pricing is separate from the engine. Use the engine for learning, and talk to Marqo about Cloud when you run a shop.

Is Marqo better than Qdrant?

Neither is better in general, because they sit in different lanes. Qdrant stores vectors you create, while Marqo creates the vectors for you. New projects in 2026 should start with Qdrant, because Marqo's engine has a final release and no future ones.

Does Marqo need a GPU?

No, Marqo runs in a Docker container on an ordinary machine, and the README includes a note for readers who want to use a GPU. The model choice affects speed more than the hardware does for a first index. Start on CPU, and add a GPU only when your index grows past what CPU search handles.

What is the default model in Marqo?

The 2.13.0 README names hf/all_datasets_v4_MiniLM-L6 as the default text model, and the quickstart example uses hf/e5-base-v2 instead. The default for the final 2.26.0 release was not verified, because the versioned docs now return 404. Pick a model by name at index creation, and do not rely on an unverified default.

Can Marqo search images?

Yes, with a CLIP model and the multimodal setting turned on at index creation. Text queries then find images, and image URLs find similar images. Without that setting, image URLs are indexed as plain strings and image search does not work.