Install & Compatibility
Where this runs
tested against v3.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.880s · 163.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 12.3s · import 1.793s · 159MB
169MB installed
● package 169MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Pipeline
✓ from haystack import Pipeline
✗ from haystack.pipelines 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
✗ from haystack.nodes import BaseComponent
Nodes are gone in 2.x. Custom components use @component decorator with a run() method.
OpenAIChatGenerator
✓ from haystack.components.generators.chat import OpenAIChatGenerator
✗ from haystack.nodes import PromptNode
PromptNode is 1.x (farm-haystack). In 2.x, use OpenAIChatGenerator or provider-specific generators.
InMemoryDocumentStore
✓ from haystack.document_stores.in_memory import InMemoryDocumentStore
✗ from haystack.document_stores import InMemoryDocumentStore
Module path changed between 1.x and 2.x. Document stores are no longer nodes/components — they are passed to Retriever components.
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)
haystack --version
Debug
Known issues
breakingHaystack 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.fixpip uninstall -y farm-haystack && pip install haystack-ai
affects: farm-haystack (all versions)
breakingfarm-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.fixpip uninstall -y farm-haystack haystack-ai && pip install haystack-ai
affects: any environment with both installed
breakingAll 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().fixRewrite pipelines using 2.x components. See migration guide: https://docs.haystack.deepset.ai/docs/migration
affects: farm-haystack 1.x code
breakingDocumentStore 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.fixReplace document store nodes with DocumentWriter component. Pass document store instances directly to Retriever components.
affects: farm-haystack 1.x code
breakingPipeline 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.fixExplicitly connect all components after adding them to the pipeline.
affects: farm-haystack 1.x code
breakingPython 3.9 support dropped as of Haystack 2.22+ (October 2025). Python 3.9 reached EOL and Haystack now requires >=3.10.fixUpgrade to Python 3.10 or later.
affects: 2.22+
gotchapip install haystack installs an unrelated package (not Haystack by deepset). The correct package name is haystack-ai.fixAlways use: pip install haystack-ai
affects: all
gotchaOptional 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.fixFollow the ImportError message, or use pip install haystack-ai[all] to include everything upfront.
affects: all 2.x
gotchaRegexTextExtractor.return_empty_on_no_match parameter removed in 2.23.0. Previously ignored since 2.22, now raises an error on initialization if passed.fixRemove return_empty_on_no_match from RegexTextExtractor initialization. The component now always returns an empty string on no match.
affects: 2.23.0+
gotchaHaystack collects anonymous telemetry by default (pipeline component usage). To opt out, set the HAYSTACK_TELEMETRY_ENABLED=false environment variable.fixexport HAYSTACK_TELEMETRY_ENABLED=false
affects: all 2.x
breakingPipeline 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`.fixEnsure 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.
affects: all 2.x
gotchaOpenAIChatGenerator (and other OpenAI components) require a valid OpenAI API key. An openai.AuthenticationError with status 401 indicates an incorrect or missing API key.fixEnsure 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.
affects: all 2.x
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'haystack.nodes'
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'.
fixEnsure 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.
ImportError: "Haystack failed to import the optional dependency 'xyz'. Run 'pip install xyz'.
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.
fixInstall 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"`.
ImportError: cannot import name 'send_event' from 'haystack.telemetry'
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.
fixUninstall both packages completely, then install only 'haystack-ai' in a clean virtual environment: `pip uninstall -y farm-haystack haystack-ai && pip install haystack-ai`.
ImportError: cannot import name 'ComponentName' from 'haystack.components.generators'
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.
fixConsult 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`.
Upgrade
Version history
3.1.0latest on PyPI · released Aug 24, 2026
Audit
Dependencies
Python >=3.10requiredPython 3.9 reached EOL in October 2025. Haystack 2.x now requires >=3.10.
pypdf, sentence-transformers, transformers, etc.optionalOptional extras — not installed by default. Haystack will raise an ImportError with a specific install instruction when a feature needs them.