Haystack
raw JSON → 2.24.x verified Tue May 12 auth: no python install: verified quickstart: verified
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.
pip install haystack-ai Common errors
error ModuleNotFoundError: No module named 'haystack.nodes' ↓
cause This error occurs when trying to use Haystack 1.x 'nodes' (from 'farm-haystack') in a Haystack 2.x environment (where the package is 'haystack-ai'). Haystack 2.x has refactored the architecture, replacing 'nodes' with 'components'.
fix
Ensure you have 'haystack-ai' installed and 'farm-haystack' uninstalled. Then, update your code to use Haystack 2.x 'components' and their new import paths as specified in the Haystack 2.x documentation.
error ImportError: "Haystack failed to import the optional dependency 'xyz'. Run 'pip install xyz'. ↓
cause Haystack 2.x adopts a modular installation approach, meaning many components rely on optional dependencies that are not installed by default. This error indicates that a specific package required by a component you are trying to use is missing.
fix
Install the missing dependency as instructed in the error message. For example, if 'xyz' is reported as missing, run:
pip install xyz. For dependencies requiring a specific version, ensure you use quotation marks: pip install "package_name>=X.Y.Z". error ImportError: cannot import name 'send_event' from 'haystack.telemetry' ↓
cause This error often arises from conflicts when both 'farm-haystack' (Haystack 1.x) and 'haystack-ai' (Haystack 2.x) are installed in the same Python environment. These two major versions are not compatible and should not coexist.
fix
Uninstall both packages completely, then install only 'haystack-ai' in a clean virtual environment:
pip uninstall -y farm-haystack haystack-ai && pip install haystack-ai. error ImportError: cannot import name 'ComponentName' from 'haystack.components.generators' ↓
cause Components for specific integrations (e.g., CohereGenerator) are often part of separate 'haystack-ai' integration packages. They must be imported from their respective package path (e.g., 'cohere_haystack.generator') rather than the generic 'haystack.components' path.
fix
Consult the documentation for the specific integration component to identify its correct import path. For instance, for CohereGenerator, the correct import is
from cohere_haystack.generator import CohereGenerator. 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
breaking Pipeline connections in Haystack 2.x require strict type compatibility between connected component sockets. A common migration issue is attempting to connect components where the output type of the source socket (e.g., a single `str` from a `PromptBuilder`) does not match the expected input type of the destination socket (e.g., `list[ChatMessage]` for an LLM), leading to a `PipelineConnectError`. ↓
fix Ensure that the output type of the source component socket explicitly matches the input type of the destination component socket. If types are incompatible, introduce an intermediate component to perform the necessary type conversion (e.g., wrap a string into a `ChatMessage` object or a list thereof) before connecting.
gotcha OpenAIChatGenerator (and other OpenAI components) require a valid OpenAI API key. An openai.AuthenticationError with status 401 indicates an incorrect or missing API key. ↓
fix Ensure the OPENAI_API_KEY environment variable is set with a valid OpenAI API key, or pass it directly to the component during initialization (e.g., OpenAIChatGenerator(api_key='sk-...')). You can find your API key at https://platform.openai.com/account/api-keys.
Install
pip install haystack-ai[all] Install compatibility verified last tested: 2026-05-12
python os / libc variant status wheel install import disk
3.10 alpine (musl) haystack-ai - - 1.87s 153.1M
3.10 alpine (musl) all - - 1.86s 153.1M
3.10 slim (glibc) haystack-ai - - 1.49s 148M
3.10 slim (glibc) all - - 1.45s 148M
3.11 alpine (musl) haystack-ai - - 2.40s 169.9M
3.11 alpine (musl) all - - 2.40s 169.9M
3.11 slim (glibc) haystack-ai - - 2.08s 164M
3.11 slim (glibc) all - - 2.04s 164M
3.12 alpine (musl) haystack-ai - - 2.46s 156.2M
3.12 alpine (musl) all - - 2.49s 156.2M
3.12 slim (glibc) haystack-ai - - 2.56s 151M
3.12 slim (glibc) all - - 2.43s 151M
3.13 alpine (musl) haystack-ai - - 2.34s 155.5M
3.13 alpine (musl) all - - 2.28s 155.5M
3.13 slim (glibc) haystack-ai - - 2.35s 150M
3.13 slim (glibc) all - - 2.34s 150M
3.9 alpine (musl) haystack-ai - - 1.82s 170.9M
3.9 alpine (musl) all - - 1.80s 170.9M
3.9 slim (glibc) haystack-ai - - 1.64s 168M
3.9 slim (glibc) all - - 1.62s 168M
Imports
- Pipeline wrong
from haystack.pipelines import Pipelinecorrectfrom haystack import Pipeline - component decorator wrong
from haystack.nodes import BaseComponentcorrectfrom haystack import component - OpenAIChatGenerator wrong
from haystack.nodes import PromptNodecorrectfrom haystack.components.generators.chat import OpenAIChatGenerator - InMemoryDocumentStore wrong
from haystack.document_stores import InMemoryDocumentStorecorrectfrom haystack.document_stores.in_memory import InMemoryDocumentStore
Quickstart verified last tested: 2026-05-11
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)