haystack-tutorials: the notebook collection that tests the Haystack API in public

What haystack-tutorials is, and what it is not

The repository holds the tutorials for Haystack, deepset's framework for retrieval-augmented generation and semantic search. The README states that these tutorials are also published to the Haystack website, so the repository is the source of truth behind a documentation surface rather than a standalone product. Every entry in the tutorial table is a .ipynb file under tutorials/, paired with a Colab badge that loads the notebook directly from the main branch.

The primary language is Jupyter Notebook, and the topics listed are generative-qa, haystack, llm, nlp, semantic-search and text-generation. That combination tells you what it is for: readers who want to see a pipeline assembled cell by cell, run it, and change one component. It is not a library, not a CLI, and not a service. There is no installable artifact in the repository. The requirements.txt at the top level lists nbconvert, pre-commit, tomli, requests and PyYAML, which are the tools used to process and validate notebooks, not Haystack itself.

The licence is Apache-2.0, which matters if you intend to copy notebook code into your own project.

The tutorial index is the product surface

The README's table is the most useful artifact in the repository. Each row maps a numbered notebook to a Colab URL, and the numbering is stable enough to cite: 27_First_RAG_Pipeline.ipynb, 28_Structured_Output_With_Loop.ipynb, 29_Serializing_Pipelines.ipynb, 30_File_Type_Preprocessing_Index_Pipeline.ipynb, 31_Metadata_Filtering.ipynb, 32_Classifying_Documents_and_Queries_by_Language.ipynb, 33_Hybrid_Retrieval.ipynb, 34_Extractive_QA_Pipeline.ipynb, 35_Evaluating_RAG_Pipelines.ipynb, 36_Building_Fallbacks_with_Conditional_Routing.ipynb, 39_Embedding_Metadata_for_Improved_Retrieval.ipynb, 40_Building_Chat_Application_with_Function_Calling.ipynb, 41_Query_Classification_with_TransformersTextRouter_and_TransformersZeroShotTextRouter.ipynb and 42_Sentence_Window_Retriever.ipynb.

Read as a sequence, that list is a curriculum. It starts with a retrieval-augmented QA pipeline, moves into structured output and serialization, then covers preprocessing, metadata filtering, language classification, hybrid retrieval, extractive QA, evaluation, conditional routing and function calling. The gaps in numbering (37 and 38 are absent from the README table) suggest notebooks were retired or renumbered, and the README does not explain why. That is a real limitation for anyone treating the numbering as a stable reference.

The Colab links point at the main branch rather than a tagged release. A notebook you open today reflects whatever was merged most recently.

How the nightly workflow keeps notebooks honest

Two GitHub Actions workflows are visible in the README badges: Run Tutorials Nightly and Publish tutorials on Haystack Home. The first is the interesting one. Notebooks rot quickly when an API changes, and a nightly execution job is the mechanism that catches a broken cell before a reader does. The README does not describe what the nightly job does on failure, whether it opens an issue, or how long a notebook may stay broken, so treat the badge as a signal rather than a guarantee.

The second workflow publishes the notebooks to the Haystack website, which explains why the repository and the site stay in step. If you are deciding whether to read here or on the website, the difference is that the repository gives you the raw .ipynb files and the git history, while the site gives you rendered pages. For anyone who wants to diff a tutorial against an older version, the repository is the only option.

The supporting files reinforce the same picture: index.toml, pyproject.toml, uv.toml, .pre-commit-config.yaml and a scripts/ directory. The pyproject.toml contains only project URLs and a Black configuration with line-length 120, so there is no packaging metadata that would let you install this as a dependency even if you wanted to.

Running your first Haystack RAG tutorial

There is nothing to pip install from this repository. The README points at Colab as the execution path, and the fastest first use is to open the first tutorial through its badge, which resolves to a Colab URL for 27_First_RAG_Pipeline.ipynb on the main branch. In Colab you run the cells in order and the pipeline is built inside the notebook session.

If you would rather work locally, clone the repository and open the notebook in Jupyter. The top-level requirements.txt covers the repository tooling, not the tutorial runtime, so the notebook cells themselves are where the Haystack dependencies appear.

git clone https://github.com/deepset-ai/haystack-tutorials.git
cd haystack-tutorials
pip install -r requirements.txt
jupyter notebook tutorials/27_First_RAG_Pipeline.ipynb

After the notebook opens, execute the cells from the top. The documentation states that this tutorial builds a first QA pipeline with retrieval augmentation, so expect the cells to construct a document store, index documents, retrieve, and generate an answer. The README does not list the exact model names or API keys the notebook expects, so read the first cells before running them and check whether an API key is required.

The repository is also set up for uv, given the uv.toml at the top level, and pre-commit is configured through .pre-commit-config.yaml for anyone contributing a notebook back.

Where the repository stops being enough

The tutorials are written against Haystack's current API at the time of each merge, and the repository pins no Haystack version. A reader who installs a different Haystack release than the one a notebook was written for will hit import errors or changed component signatures, and the README offers no compatibility table. The nightly workflow reduces how often that happens but does not eliminate it, because it tests against whatever Haystack version the environment resolves.

There is also no rollback guidance. The README does not document how to find the notebook revision that matched an older Haystack release, so downgrading means reading git history yourself. For a team that needs a reproducible example pinned to a specific Haystack version, this repository is the wrong tool; you want a tagged release or a lockfile, and neither is present here.

Finally, the notebooks are teaching artifacts. They are not hardened for production, and the README makes no claim that they are. Copying a retrieval pipeline out of a tutorial into a service means replacing the defaults, adding error handling and deciding on your own document store, none of which the tutorials cover.

Haystack tutorials versus LangChain examples

The comparison people reach for is Haystack against LangChain, and the notebook collections show the split clearly. Haystack's tutorials build explicit pipelines: you connect components such as retrievers, routers and generators, and tutorials like 36_Building_Fallbacks_with_Conditional_Routing.ipynb and 33_Hybrid_Retrieval.ipynb exist because the wiring itself is the subject. Serialization is a first-class topic here, which is why 29_Serializing_Pipelines.ipynb is in the list.

LangChain's examples tend toward chaining abstractions and integrations, where the framework supplies more of the control flow. The practical difference for a reader is what you learn. Working through haystack-tutorials teaches you how a retrieval pipeline is assembled and evaluated, including the evaluation notebook 35_Evaluating_RAG_Pipelines.ipynb. Working through a chain-oriented example set teaches you how to compose a framework's building blocks quickly.

Neither approach is better in the abstract. If your team wants to reason about retrieval quality and inspect each stage, the Haystack tutorial sequence maps more directly onto that work. If you want the shortest path to a working prototype across many providers, the Haystack notebooks will feel more explicit than you need.

Maintenance, licence and the cost of following along

The repository is not archived, and the last push was on 2026-09-07, which is recent enough that the tutorials track the current Haystack API. There are no releases in the repository, so there is no versioned artifact to upgrade and no changelog to read. Upgrading means pulling main and re-running the notebook, which is cheap if you use Colab and more work if you have forked the notebooks into your own tree.

The cost that matters is not upgrade cost but drift. Every Haystack release can invalidate a cell, and the nightly workflow is what surfaces that. If you fork a notebook and stop pulling, you inherit the drift without the nightly signal.

The licence is Apache-2.0, which permits reuse and modification with the usual attribution and notice requirements. That is a permissive licence, but the tutorials may reference models, datasets or APIs with their own terms, and the repository does not enumerate them. Check the individual notebook before shipping code derived from it.

Editorial conclusion

Adopt this repository if you are learning Haystack pipeline construction and want runnable notebooks rather than prose, or if you maintain Haystack-adjacent content and want to see how deepset structures examples. Do not adopt it as a dependency: there is no package to install, only notebooks and a requirements.txt listing nbconvert, pre-commit, tomli, requests and PyYAML. Before relying on any single notebook, open its Colab link and check that the cells still execute against your installed Haystack version, because the repository pins nothing and the nightly workflow is the only signal that a tutorial still runs.

Frequently asked questions

Official sources

1. deepset-ai/haystack-tutorials on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README