How to migrate Haystack 1.x code to Haystack 2.x

Older Haystack projects usually carry two kinds of 1.x assumptions: the Python dependency is named farm-haystack, and pipeline code is written around named nodes connected through add_node(). Moving that code to Haystack 2.x means resetting the package environment and rewriting the pipeline as explicit components with typed inputs and outputs.

The 2.x distribution is installed as haystack-ai, while application code still imports the haystack module. Keep the old and new packages out of the same Python environment so import resolution, dependencies, and generated component graphs all come from one Haystack generation.

A small migration pass should prove the new package, the new import surface, and one working Pipeline.run() call before larger retrievers, generators, document stores, or custom nodes are moved. After that smoke test works, migrate each 1.x node to the matching 2.x component or integration package and keep the old code available for behavior comparison until the replacement pipeline returns the expected output.

Steps to migrate Haystack 1.x code to Haystack 2.x:

Create a branch or copy of the 1.x application before changing dependencies.

Keep the old project available until the 2.x pipeline returns matching answers or documents for the same sample inputs.
Replace the old package dependency with the current Haystack package.
```
haystack-ai
```
Use the project file that actually controls the environment, such as requirements.txt, pyproject.toml, Pipfile, or a lockfile workflow. Remove farm-haystack from that dependency set.

Remove old and conflicting Haystack packages from the active environment.

$ python -m pip uninstall --yes farm-haystack haystack-ai
WARNING: Skipping farm-haystack as it is not installed.
Found existing installation: haystack-ai 2.30.2
Uninstalling haystack-ai-2.30.2:
  Successfully uninstalled haystack-ai-2.30.2

farm-haystack and haystack-ai should not share one Python environment. Resetting both packages first avoids importing a stale module while migration tests run.

Install the Haystack 2.x package.

$ python -m pip install haystack-ai
Collecting haystack-ai
  Using cached haystack_ai-2.30.2-py3-none-any.whl.metadata
##### snipped #####
Using cached haystack_ai-2.30.2-py3-none-any.whl
Installing collected packages: haystack-ai
Successfully installed haystack-ai-2.30.2

Install any integration packages only when the migrated pipeline imports those components, such as vector store, document converter, embedding, or tracing integrations.
Related: How to install Haystack with pip

Confirm that the legacy package is no longer installed.

$ python -m pip show farm-haystack
WARNING: Package(s) not found: farm-haystack

Inventory each legacy pipeline node before rewriting the script.

Treat 1.x nodes as a migration checklist. Replace imports from haystack.nodes with current haystack.components imports, integration packages, or small custom components, then replace add_node(…, inputs=…) with add_component() and connect() calls.

Create a migrated 2.x pipeline script.

from haystack import Pipeline, component
import haystack
 
 
@component
class QueryNormalizer:
    @component.output_types(clean_query=str)
    def run(self, query: str):
        return {"clean_query": " ".join(query.strip().split())}
 
 
@component
class MigrationResponder:
    @component.output_types(answer=str)
    def run(self, clean_query: str):
        return {
            "answer": (
                "Haystack 2.x pipeline migrated for question: "
                f"{clean_query}"
            )
        }
 
 
pipeline = Pipeline()
pipeline.add_component("normalizer", QueryNormalizer())
pipeline.add_component("responder", MigrationResponder())
pipeline.connect("normalizer.clean_query", "responder.clean_query")
 
result = pipeline.run(
    {"normalizer": {"query": "  What changed in Haystack 2?  "}}
)
 
print(f"Haystack {haystack.__version__}")
print(result["responder"]["answer"])

The custom components stand in for one small migrated path. Larger applications should move one old node group at a time, then check each component's input and output names before connecting the next stage.

Run the migrated pipeline script.
```
$ python migrated_pipeline.py
Haystack 2.30.2
Haystack 2.x pipeline migrated for question: What changed in Haystack 2?
```
The script imports the 2.x haystack module, connects typed component outputs to inputs, and returns output from the final component through Pipeline.run().