Installation

Install indx in layers. The base package is small, and each parser, model provider, embedder, store, and framework writer is an optional extra. Start with the stack you need today; add another backend later by installing its extra and changing a slot name.

This page covers requirements, common install paths, the extras matrix, and the missing-extra errors indx raises when a selected backend is not installed.

Requirements

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

Why not 3.10?

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

Install the base package

pip install indx

The base 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.

That buys you several things at once:

• pip install indx stays small and fast.
• The cloud-backed default is explicit, not implicit.
• A local profile stays first-class.
• No 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 zero-dependency run is built in

Even with nothing but the base package installed, indx includes a complete offline stack for plain-text corpora. Use --offline, or select the same slots explicitly, to avoid every optional backend:

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

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

That command uses plaintext, none, hash, jsonl, and .indx to produce a usable, self-contained .indx archive with no extras, no database, and no network.

The trade-off is quality and scale:

• plaintext only reads text.
• hash is lexical rather than semantic.
• jsonl does a brute-force linear scan suited to small corpora.

Local-first stays first-class

The default runtime stack is cloud-backed and optimized for quality. The local profile (Docling + Ollama + BGE-M3 + Qdrant) is the richer offline stack; install indx[local] when data residency or air-gapped operation matters. Use --offline when you want the lightest possible zero-extra path. See the air-gapped guide for both.

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[cloud]"

Set OPENAI_API_KEY before running:

export OPENAI_API_KEY="..."

This is equivalent to pip install "indx[docling,openai,qdrant]".

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.

defaults the bundle ≠ the runtime defaults

The install bundle named defaults selects the local stack (Docling + Ollama + BGE-M3 + Qdrant). That 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 base package — no extras:

pip install indx

Run the zero-dependency stack with --offline:

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

Add a single extra when you want a richer 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[cloud]" | The default cloud-backed runtime stack: Docling + OpenAI + Qdrant | | 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 the 'qdrant' extra: 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. An --offline build using plaintext, hash, and jsonl 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 build on a small directory. Use the default stack if you installed its extras and set OPENAI_API_KEY, or use --offline for the zero-dependency core stack:

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

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.