How Do I Get Started with Haystack?

Updated

Install Haystack into a Python environment, then build a minimal pipeline that connects a document store, a retriever, and a generator. That three-part structure is the core of almost every Haystack application, so getting one running end to end is the fastest way to understand the framework. The steps below assume you are comfortable with the command line and have Python available; you do not need prior experience with Haystack itself.

Prerequisites

Before installing anything, confirm you have:

  • Python 3.8 or newer — Haystack 2.x targets modern Python versions. Check with python --version.
  • pip — the standard package installer, normally bundled with Python. Check with pip --version.
  • A virtual environment (recommended) — isolates Haystack and its dependencies from your system packages.
python -m venv haystack-env
source haystack-env/bin/activate   # Windows: haystack-env\Scripts\activate

If you plan to use a hosted model provider for generation or embeddings, have that provider's API key ready. Haystack integrates with multiple providers, and the specific key depends on which one you choose.

Install Haystack

Install the core package with pip:

pip install haystack-ai

The core install gives you the pipeline framework and the base component interfaces. Integrations with specific model providers, vector databases, and file converters are distributed as separate packages, so you add only what your application needs. If you already know which provider you will use, install its integration package alongside the core.

Expected result: pip show haystack-ai lists an installed version, and python -c "import haystack" runs without error.

Common snag: If installation fails on a dependency, upgrade pip first (pip install --upgrade pip) and retry. Version conflicts are the most frequent cause.

Build a Minimal Pipeline

A working Haystack pipeline has three conceptual pieces:

Piece Role
Document store Holds your documents and their embeddings so they can be searched.
Retriever Takes a query and returns the most relevant documents from the store.
Generator Takes the retrieved documents plus the query and produces a natural-language answer.

You connect these as components inside a Pipeline object, wiring each component's output to the next component's input. The pipeline then runs as a directed graph: the query enters, documents are retrieved, and an answer comes out.

A minimal flow looks like this:

  1. Create a document store and write a few documents into it. For a first test, an in-memory store avoids any external service setup.
  2. Add a retriever that embeds the query and searches the store.
  3. Add a generator that receives the retrieved documents and the original query.
  4. Connect the components by declaring which output feeds which input.
  5. Run the pipeline with a query string and inspect the result.

Expected result: Running the pipeline returns an answer grounded in the documents you loaded.

Common snag: If the retriever returns nothing, check that documents were actually written to the store and that the embedding model used at write time matches the one used at query time. Mismatched embedding models are a frequent cause of empty results.

Where to Go Next

Once the minimal pipeline runs, the documentation's tutorial and concept sections are the right next stop. They explain:

  • How pipelines are structured — the component-and-connection model, and how data flows between components.
  • Which components exist — retrievers, rankers, converters, generators, and how to swap one provider for another.
  • How to persist documents — moving from an in-memory store to a database-backed store for real workloads.

Reading the concept pages before building a larger application will save time, because most Haystack errors trace back to a misunderstanding of how components connect rather than to the components themselves.