haystack-cookbook: what the notebook collection actually gives you

What haystack-cookbook is, and what it is not

The repository describes itself as a collection of example notebooks using Haystack, maintained by deepset-ai. Each notebook, per the README, is meant to "showcase a specific, small demo": a particular model provider, a vector database, a retrieval technique, or an experimental feature. That framing matters. This is not a framework, a library, or a service. It is a set of worked examples, and the README points readers elsewhere for conceptual grounding, directing them to the Haystack docs and the official tutorials for learning how to use the framework itself.

The audience is therefore narrow and specific. If you already know you want to build with Haystack and you want to see how a given integration is wired up in practice, the cookbook is the intended entry point. If you have not chosen a framework yet, the notebooks will show you Haystack idioms before you have any basis for comparison, which is a poor way to evaluate it. The README also runs a contribution path for people who have written an example and want to share it, including a Colab route where you fork the repository, save a copy to GitHub, and open a pull request from the fork.

How the notebooks are organised and indexed

The repository layout is small: a notebooks folder, a data folder, an index.toml file, a requirements.txt, a scripts folder, and the usual GitHub metadata. The interesting piece is index.toml. The README's contribution instructions require that every notebook added to the notebooks folder also be added to index.toml with its title and topics. That file is what drives the browsable cookbook at haystack.deepset.ai/cookbook, so the index is the actual catalogue rather than a convenience.

The README adds one conditional field. If a notebook uses an experimental feature, the contributor must also add the discussion link and set the experimental field to true. That is a useful signal for a reader deciding whether to build on what they see. A notebook demonstrating an experimental feature is documenting something that may change or disappear, and the index marks it as such. The requirements.txt at the repository root is minimal, listing only nbconvert, which tells you the repository's own tooling is about converting or executing notebooks rather than pinning a runtime for you. There is no lockfile for the examples themselves, so each notebook carries its own install assumptions.

Running a notebook from the cookbook

There is no install step for the cookbook as a whole. You clone the repository and open a notebook, and the notebook's own cells carry the dependencies it needs. The only repository-level requirement file exists to support notebook tooling:

pip install -r requirements.txt

That installs nbconvert, which is used for notebook conversion. It does not install Haystack, and it does not install any model provider or vector database client. Those come from the notebook you choose.

A typical first use is to pick an entry from index.toml, open the corresponding file under notebooks, and run it cell by cell. Because the README describes the examples as small demos for specific providers and databases, expect a notebook to begin with its own pip install line and its own API key configuration. The repository does not supply credentials, and the README does not document a shared environment file. If you want to contribute a notebook back, the README gives a concrete naming rule:

# add your notebook to /notebooks
# give it a descriptive name covering providers, databases, technologies and task
# then register it in index.toml with its title and topics

The naming convention is the part people skip. A file called demo.ipynb tells a reader nothing; a name that names the provider, the database and the task lets the index and the site listing stay useful.

Where the cookbook falls short

The main limitation is version drift, and it follows directly from the structure. The notebooks are examples, not a released artefact. There are no releases in the repository, no versioned tags for the examples, and no compatibility matrix tying a notebook to a Haystack version. A notebook written against one set of component names and constructor arguments may not run against a later Haystack release without edits. The README does not document a policy for updating old notebooks when the framework changes, and it does not say that notebooks are tested on a schedule.

The second limitation is scope. The README is explicit that these are small demos, and that the docs and tutorials are where you go to learn how to use Haystack. That means the cookbook is a poor substitute for the documentation if you need to understand a concept rather than copy a pattern. It also means the examples are not production blueprints. There is no discussion in the README of error handling, retries, evaluation, or deployment. If you need those, the cookbook will not supply them, and you should not read a working demo as an endorsement of the approach for a real workload.

A third issue is discovery. Everything routes through index.toml, so a notebook that exists in the notebooks folder but is missing from the index is effectively invisible on the site. The contribution instructions guard against this, but it is a manual step, and manual steps fail.

How it compares to the official tutorials and the blog

The README itself points to two neighbours: the official tutorials and the blog, both on haystack.deepset.ai. The difference is in shape and intent. Tutorials are structured teaching material, sequenced so that each step builds on the last and the reader ends with a working understanding of a concept. The cookbook is a flat collection of independent demos, each self-contained, each solving a narrow integration question. The blog is prose and narrative, useful for context and announcements rather than for copying code.

So the choice is about what you need. If you are learning retrieval augmented generation from scratch, start with the tutorials; a cookbook entry assumes you already know what you are looking at. If you already understand the framework and want to see how a specific vector database or model provider is wired in, the cookbook is the faster route. And if you want to know why a feature exists or where the project is heading, the blog is the better source. Treating the cookbook as the primary learning path inverts the intended order.

Maintenance, licensing and the cost of keeping up

The repository is not archived, and its last push was on 2026-09-08, which is recent. That tells you the collection is still receiving changes, but it says nothing about whether any individual notebook has been re-run against the current framework. The distinction matters when you are deciding whether to build on an example: an active repository index can sit on top of notebooks that have quietly stopped working.

The README does not state a licence for the repository, and no licence file appears among the top-level entries. If you intend to reuse notebook code in your own project, that is the first thing to resolve, because the absence of an explicit licence leaves the terms unclear. This is not legal advice; it is a pointer to check before copying code into a commercial codebase.

Upgrade cost is the real ongoing expense. Because the examples are not versioned as a unit, keeping a notebook working is your responsibility once you copy it. The practical approach is to pin the Haystack version your notebook was written against, keep the notebook's own dependency installs in a dedicated environment, and re-run it when you move that pin. The repository gives you no mechanism to do this for you.

Editorial conclusion

Adopt haystack-cookbook if you learn from runnable examples and want to see how Haystack components fit together across providers and retrieval techniques. Do not treat it as a dependency or a supported API; nothing in the repository is versioned for consumption as a package. Before relying on any notebook, check the index.toml entry for an experimental flag and confirm the notebook still imports against your installed haystack-ai version, because the collection is a moving set of demos rather than a frozen release.

Frequently asked questions

Official sources

1. deepset-ai/haystack-cookbook on GitHub
2. Issues
3. Project website
4. README