Installation

indx ships as a deliberately tiny core plus a matrix of optional extras. You install the small base with pip install indx, then add only the backends your stack actually needs — a parser, an LLM, an embedder, a store. This page covers the requirements, the install model, every extra, the convenience bundles, and how indx tells you exactly which extra to add when one is missing.

Requirements

• Python 3.11+ (supported on 3.11, 3.12, and 3.13). 3.11 is the floor because indx relies on stdlib tomllib, modern typing primitives (Self, LiteralString), and ExceptionGroup / except* for fan-out error handling — all without backports.
• A virtual environment is recommended (python -m venv .venv && . .venv/bin/activate).
• The base install works on Linux, macOS, and Windows with no native build step.

Why not 3.10?

indx deliberately does not floor at 3.12+ either: several ML and vector backends lag a Python release behind, and forcing a newer floor would shrink the install base. 3.11–3.13 keeps you on actively supported runtimes.

Install the core

pip install indx

The core install is intentionally light. It pulls in only:

Dependency	Role
Typer	Type-annotated CLI surface
Rich	Terminal rendering: progress, tables, tracebacks
Click	Underlying CLI argument parser Typer builds on
Pydantic v2	All boundary data models and validation
pydantic-settings	Layered config: defaults, indx.toml, environment, CLI

TOML parsing uses the standard library’s tomllib, so there is no parsing dependency. No parser toolchain, no Torch, no vector-DB client, and no cloud SDK is installed by the base package.

Why the core is light

indx composes parsers and models; it does not bundle them. Heavy local runtimes and cloud dependencies (Docling, Torch, Qdrant clients, OpenAI/Anthropic SDKs) are each an optional extra, never a core requirement. This keeps pip install indx small and fast, makes the cloud-backed default explicit, preserves a first-class local profile, and avoids vendor lock-in — swapping a backend is a config change, not a reinstall of the world. See the architecture overview and design principles for the reasoning.

A full run works with zero extras

Even with nothing but the core installed, a complete build runs offline, because the core ships zero-dependency fallbacks for the slots that would otherwise need a backend:

Slot	Built-in fallback
Parser	plaintext
Store	jsonl (no database)
VLM	none (skips vision enrichment)
Output writer	.indx and jsonl

That means indx ./docs --out ./ai-ready produces a usable, self-contained .indx archive with no extras, no database, and no network. The fallbacks trade quality and scale for portability — the plaintext parser only reads text, and the jsonl store does a brute-force linear scan suited to small corpora.

Local-first stays first-class

The cloud-backed defaults are for the broadest install-and-run path. The local profile (Docling + Ollama + BGE-M3 + Qdrant) remains a first-class, fully offline stack; install indx[local] when data residency or air-gapped operation matters. See the air-gapped guide for the complete offline path.

Choose an install path

Recommended

The recommended cloud-backed stack uses Docling for parsing, OpenAI for text enrichment and embeddings, and Qdrant for storage:

pip install "indx[docling,openai,qdrant]"

Set OPENAI_API_KEY before running:

export OPENAI_API_KEY="..."

Local / air-gapped

The local profile — Docling parser, local Ollama LLM, BGE-M3 embedder, and Qdrant store — in one command:

pip install "indx[local]"

indx[local] and indx[defaults] are aliases for the same curated bundle. After installing, two more local prerequisites complete the offline stack.

Note: the install bundle named defaults selects the local stack (Docling + Ollama + BGE-M3 + Qdrant) — it is not the same as indx’s runtime component defaults, which are cloud-backed (Docling + openai:gpt-5-mini + text-embedding-3-small + Qdrant). The bundle is a packaging convenience; the runtime defaults are what a bare indx <dir> --out <dir> uses.

Pull an Ollama model. The local profile uses ollama:qwen2.5, so install Ollama and pull the model:

ollama pull qwen2.5

Docling and BGE-M3 may download models on first run. Run the stack once while online so the weights are cached, then subsequent runs are offline.

Minimal

Just the core — no extras. A full build still works using the built-in plaintext parser, jsonl store, none VLM, and .indx/jsonl writers:

pip install indx

Add a single extra when you want a real parser or store, for example a light Markdown-first setup:

pip install "indx[markitdown]"

Everything

Every backend across all six slots — handy for trying things out or for CI:

pip install "indx[all]"

This is large (it pulls Torch, multiple parsers, and several DB clients). Prefer a targeted set of extras for real projects.

Quote the brackets

In zsh (the default macOS shell) square brackets are glob characters. Always quote the spec — pip install "indx[local]" — or the install will fail to resolve.

The extras matrix

Each extra enables one or more implementations and pulls only that backend’s dependencies. Pick per slot.

Parsers

| Install | Enables | Slot | |---|---|---| | pip install "indx[docling]" | Docling parser (the default; high-fidelity layout, local) | parser | | pip install "indx[markitdown]" | MarkItDown parser (lightest local option) | parser |

See choosing a parser for the trade-offs.

LLMs and VLMs

| Install | Enables | Slot | |---|---|---| | pip install "indx[openai]" | OpenAI LLM (default gpt-5-mini), embedder, and GPT-4o VLM | llm / vlm / embed | | pip install "indx[ollama]" | Ollama LLM (qwen2.5 in the local profile) | llm | | pip install "indx[anthropic]" | Anthropic LLM | llm |

VLM defaults to none; enable a vision model only when you want figure and image descriptions. See enrichment with LLMs and VLMs.

Embedders

| Install | Enables | Slot | |---|---|---| | pip install "indx[openai]" | OpenAI embedder (default text-embedding-3-small, API, light) | embed | | pip install "indx[bge]" | BGE-M3 embedder (local profile, dim 1024; pulls Torch) | embed |

Local embedding is the heaviest optional path because it pulls Torch and model weights. See choosing an embedder.

Stores

| Install | Enables | Slot | |---|---|---| | pip install "indx[qdrant]" | Qdrant store (the default; embedded or server) | store | | pip install "indx[pgvector]" | pgvector store (Postgres) | store | | pip install "indx[chroma]" | Chroma store | store | | pip install "indx[lancedb]" | LanceDB store (file-based, columnar) | store |

The built-in jsonl store needs no extra at all. See choosing a store.

Output / framework writers

| Install | Enables | Slot | |---|---|---| | pip install "indx[langchain]" | LangChain Document writer | output | | pip install "indx[llamaindex]" | LlamaIndex node writer | output |

The .indx and jsonl writers ship in core. See output formats.

Bundles

| Install | What you get | |---|---| | pip install "indx[local]" / pip install "indx[defaults]" | The recommended local / air-gapped stack: Docling + Ollama + BGE-M3 + Qdrant | | pip install "indx[all]" | Every extra above, unioned |

For the complete, authoritative list of extras and the exact packages each pulls, see the extras reference.

Combining extras

Extras compose — request several at once with commas:

pip install "indx[docling,bge,qdrant,openai]"

This installs the Docling parser, the local BGE-M3 embedder, the Qdrant store, and the OpenAI SDK (for an OpenAI LLM/embedder) — a typical hybrid local-parse / cloud-LLM setup.

Missing extras: actionable errors

Because backends are optional, indx is designed so that a missing dependency produces a precise, actionable message — and only when that slot is actually selected.

• If you select a backend whose extra is not installed (for example store = "qdrant" without indx[qdrant]), the run fails fast with an error that names the exact command to fix it:

  MissingDependencyError: store 'qdrant' requires: pip install indx[qdrant]

• The error is raised lazily. The registry resolves a backend only when its slot is chosen, so an installed-but-unused plugin — or simply not having an extra you do not use — never breaks an unrelated run. A plaintext + jsonl core-only build is never affected by missing parser or store extras.

This behaviour (surfaced through MissingDependencyError) is the contract that lets the core stay light without trapping you later. See errors and exit codes for the full hierarchy.

Verify your install

1. Confirm the CLI is on your path and prints a version:

   indx --version

2. Run a zero-config build on a small directory — this works even with a core-only install via the built-in fallbacks:

   indx ./docs --out ./ai-ready

3. Inspect the resulting archive:

   indx inspect ./ai-ready/handbook.indx

If indx inspect prints a document tree and counts, your install is working. The CLI reference documents every command and flag.

Next steps

Quickstart Build your first knowledge space in a few commands.

Build a knowledge space A guided end-to-end first run.

Local & air-gapped The complete fully-offline install and run path.

Extras reference The full, authoritative matrix of extras and packages.