Environment:Neuml Txtai Optional Extras Dependencies

Knowledge Sources	txtai txtai Installation
Domains	Infrastructure, NLP
Last Updated	2026-02-10 00:00 GMT

Overview

Modular optional dependency groups for txtai features including agents, pipelines, API server, training, and vector backends.

Description

txtai uses a modular dependency system organized into extras groups. Each group enables a specific set of features. Dependencies are installed via pip extras syntax (e.g., `pip install txtai[api]`). The codebase uses conditional imports with `try/except ImportError` patterns and boolean flags (e.g., `PEFT = True`) to gracefully handle missing optional packages, raising clear error messages when features are used without their dependencies.

Usage

Install the specific extras needed for your use case. Only the base dependencies are required for core semantic search. Additional extras are needed for agents (`smolagents`), API deployment (`fastapi`), training (`peft`, `accelerate`), LLM pipelines (`litellm`, `llama-cpp-python`), and other features.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	Some extras have platform-specific requirements
Python	>= 3.10	Same as core
Java	Optional (for Tika)	Required by `pipeline-data` extra for `tika` text extraction
C++ Build Tools	Optional (Windows)	Required for compiling `bitsandbytes`, `hnswlib`, etc.

Dependencies

Agent Extras

`jinja2` >= 3.1.6
`mcpadapt` >= 0.1.0
`smolagents` >= 1.23

API Extras

`aiohttp` >= 3.8.1
`fastapi` >= 0.94.0
`fastapi-mcp` >= 0.2.0
`httpx` >= 0.28.1
`pillow` >= 7.1.2
`python-multipart` >= 0.0.7
`uvicorn` >= 0.12.1

ANN Extras

`annoy` >= 1.16.3
`bitsandbytes` >= 0.42.0
`ggml-py` >= 0.9.4
`hnswlib` >= 0.5.0
`pgvector` >= 0.4.1
`scikit-learn` >= 0.23.1
`scipy` >= 1.4.1
`sqlalchemy` >= 2.0.20
`sqlite-vec` >= 0.1.1

Pipeline Train Extras

`accelerate` >= 0.26.0
`bitsandbytes` >= 0.42.0
`onnx` >= 1.11.0
`onnxmltools` >= 1.9.1
`onnxruntime` >= 1.11.0
`peft` >= 0.8.1
`skl2onnx` >= 1.9.1

Pipeline LLM Extras

`httpx` >= 0.28.1
`litellm` >= 1.37.16
`llama-cpp-python` >= 0.2.75

Vector Extras

`litellm` >= 1.37.16
`llama-cpp-python` >= 0.2.75
`model2vec` >= 0.3.0
`scikit-learn` >= 0.23.1
`scipy` >= 1.4.1
`sentence-transformers` >= 5.0.0
`skops` >= 0.9.0
`staticvectors` >= 0.2.0

Workflow Extras

`apache-libcloud` >= 3.3.1
`croniter` >= 1.2.0
`openpyxl` >= 3.0.9
`pandas` >= 1.1.0
`pillow` >= 7.1.2
`requests` >= 2.26.0
`xmltodict` >= 0.12.0

Credentials

`TIKA_JAVA`: Path to Java executable for Tika text extraction (defaults to `java`)
`ALLOW_PICKLE`: Set to `True` or `1` to enable loading pickled index data (security-sensitive)

Quick Install

# Install specific extras
pip install txtai[agent]
pip install txtai[api]
pip install txtai[pipeline]
pip install txtai[pipeline-train]

# Install multiple extras
pip install txtai[api,pipeline,workflow]

# Install everything
pip install txtai[all]

Code Evidence

Conditional import pattern from `agent/__init__.py:4-12`:

try:
    from .base import Agent
    from .factory import ProcessFactory
    from .model import PipelineModel
    from .tool import *
except ImportError:
    from .placeholder import Agent

Placeholder error from `agent/placeholder.py:12-16`:

class Agent:
    def __init__(self, *args, **kwargs):
        raise ImportError('smolagents is not available - install "agent" extra to enable')

PEFT conditional import from `pipeline/train/hftrainer.py:24-32`:

try:
    from peft import LoraConfig, TaskType, get_peft_model, prepare_model_for_kbit_training
    from transformers import BitsAndBytesConfig
    PEFT = True
except ImportError:
    PEFT = False

llama.cpp conditional import from `pipeline/llm/llama.py:10-15`:

try:
    import llama_cpp as llama
    LLAMA_CPP = True
except ImportError:
    LLAMA_CPP = False

Common Errors

Error Message	Cause	Solution
`ImportError: smolagents is not available - install "agent" extra to enable`	Agent dependencies not installed	`pip install txtai[agent]`
`ImportError: PEFT is not available - install "pipeline" extra to enable`	Training dependencies not installed	`pip install txtai[pipeline-train]`
`ImportError: llama.cpp is not available - install "pipeline" extra to enable`	llama.cpp not installed	`pip install txtai[pipeline-llm]`
`ImportError: onnxruntime is not available - install "model" extra to enable`	ONNX runtime not installed	`pip install txtai[model]`
`ImportError: bitsandbytes is not available - install "ann" extra to enable`	bitsandbytes not installed	`pip install txtai[ann]`
`ImportError: LiteLLM is not available - install "pipeline" extra to enable`	litellm not installed	`pip install txtai[pipeline-llm]`

Compatibility Notes

Extras are additive: Each extras group can be combined (e.g., `txtai[api,pipeline,workflow]`).
The `all` extra includes everything except dev dependencies.
The `similarity` extra is a backwards-compatible alias combining `ann` + `vectors`.
The `pipeline` extra combines all pipeline sub-extras (`audio`, `data`, `image`, `llm`, `text`, `train`).

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment