Haystack

2.24.x · active · verified Sat Feb 28

Open-source AI orchestration framework by deepset for building production-ready LLM applications in Python. Core abstraction is the Pipeline — a computation graph of Components (embedders, retrievers, generators, rankers, etc.) connected via explicit typed edges. Supports RAG, agents, semantic search, and multimodal workflows. Integrates with OpenAI, Anthropic, Mistral, Hugging Face, Azure, Bedrock, and 70+ vector databases and document stores.

Warnings

breaking Haystack 1.x (farm-haystack) reached End of Life on March 11, 2025. Final version is 1.26.4. No further updates or security patches. The correct package for Haystack 2.x is haystack-ai, NOT farm-haystack.
Fix: pip uninstall -y farm-haystack && pip install haystack-ai
breaking farm-haystack and haystack-ai CANNOT coexist in the same Python environment. Installing both causes import conflicts and unpredictable failures — haystack namespace is shared but incompatible between the two packages.
Fix: pip uninstall -y farm-haystack haystack-ai && pip install haystack-ai
breaking All 1.x Nodes are gone in 2.x. Pipeline.add_node() does not exist. The entire node API (BaseComponent subclasses, PromptNode, FARMReader, EmbeddingRetriever, etc.) has been replaced with Components using the @component decorator and Pipeline.add_component() + Pipeline.connect().
Fix: Rewrite pipelines using 2.x components. See migration guide: https://docs.haystack.deepset.ai/docs/migration
breaking DocumentStore is no longer a pipeline component/node in 2.x. In 1.x, a DocumentStore could be the terminal node of an indexing pipeline. In 2.x, DocumentStores are plain Python objects passed to Retriever components. Use DocumentWriter component to write to a store at the end of a pipeline.
Fix: Replace document store nodes with DocumentWriter component. Pass document store instances directly to Retriever components.
breaking Pipeline connections must be explicit in 2.x. In 1.x, nodes were chained implicitly in order. In 2.x, you must call pipeline.connect('component_a.output_name', 'component_b.input_name') for every edge — both the component name AND the socket name are required.
Fix: Explicitly connect all components after adding them to the pipeline.
breaking Python 3.9 support dropped as of Haystack 2.22+ (October 2025). Python 3.9 reached EOL and Haystack now requires >=3.10.
Fix: Upgrade to Python 3.10 or later.
gotcha pip install haystack installs an unrelated package (not Haystack by deepset). The correct package name is haystack-ai.
Fix: Always use: pip install haystack-ai
gotcha Optional dependencies (pypdf, sentence-transformers, transformers, etc.) are NOT included in the base install. Components that need them will raise an ImportError at runtime with the specific pip install command needed. This is by design for a lightweight install.
Fix: Follow the ImportError message, or use pip install haystack-ai[all] to include everything upfront.
gotcha RegexTextExtractor.return_empty_on_no_match parameter removed in 2.23.0. Previously ignored since 2.22, now raises an error on initialization if passed.
Fix: Remove return_empty_on_no_match from RegexTextExtractor initialization. The component now always returns an empty string on no match.
gotcha Haystack collects anonymous telemetry by default (pipeline component usage). To opt out, set the HAYSTACK_TELEMETRY_ENABLED=false environment variable.
Fix: export HAYSTACK_TELEMETRY_ENABLED=false

Install

pip install haystack-ai Install Haystack 2.x (correct package)
pip install haystack-ai[all] Install with all optional extras

Imports

Pipeline
```
from haystack import Pipeline
```
Haystack 2.x top-level import. The haystack.pipelines module path is from 1.x (farm-haystack).
component decorator
```
from haystack import component
```
Nodes are gone in 2.x. Custom components use @component decorator with a run() method.
OpenAIChatGenerator
```
from haystack.components.generators.chat import OpenAIChatGenerator
```
PromptNode is 1.x (farm-haystack). In 2.x, use OpenAIChatGenerator or provider-specific generators.
InMemoryDocumentStore
```
from haystack.document_stores.in_memory import InMemoryDocumentStore
```
Module path changed between 1.x and 2.x. Document stores are no longer nodes/components — they are passed to Retriever components.

Quickstart

Simple RAG pipeline with in-memory document store

import os
from haystack import Pipeline
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
from haystack.components.builders import PromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage

os.environ["OPENAI_API_KEY"] = "sk-..."

document_store = InMemoryDocumentStore()
# Index docs separately: document_store.write_documents([...])

template = """
Given the following context, answer the question.
Context: {% for doc in documents %}{{ doc.content }}{% endfor %}
Question: {{ question }}
"""

pipeline = Pipeline()
pipeline.add_component("retriever", InMemoryBM25Retriever(document_store=document_store))
pipeline.add_component("prompt", PromptBuilder(template=template))
pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o"))

pipeline.connect("retriever.documents", "prompt.documents")
pipeline.connect("prompt.prompt", "llm.messages")

result = pipeline.run({"retriever": {"query": "What is Haystack?"}, "prompt": {"question": "What is Haystack?"}})
print(result["llm"]["replies"][0].text)

view raw JSON →