Install Hamilton Dataflow in Python

The Hamilton dataflow framework helps you write clean, modular, and reusable data pipelines in Python. It lets you define transformations as functions and then automatically builds a directed acyclic graph (DAG) from them. This makes your code easier to test, debug, and scale.

In this guide, you will learn how to install Hamilton on your system. We cover pip, conda, virtual environments, and common troubleshooting steps. By the end, you will have a working Hamilton setup ready for your first dataflow.

Prerequisites

Before installing Hamilton, ensure you have Python 3.8 or newer. You can check your Python version by opening a terminal and running:

python --version

If you see a version below 3.8, update Python first. Hamilton also works best with pip version 21 or higher. Upgrade pip with:

python -m pip install --upgrade pip

Install Hamilton with pip

The simplest way to install Hamilton is via pip. Open your terminal and run:

pip install "sf-hamilton[visualization]"

This command installs the core Hamilton library along with optional visualization support. The visualization extra lets you render your DAG as an image, which is very helpful for debugging.

After installation, verify it worked by importing Hamilton in Python:

# Check if Hamilton is installed correctly
import hamilton
print(hamilton.__version__)

Expected output (your version may differ):

1.70.0

If you see a version number, Hamilton is installed. If you get a ModuleNotFoundError, go back and check your pip command.

Install Hamilton with conda

If you use Anaconda or Miniconda, you can install Hamilton from the conda-forge channel. Run:

conda install -c conda-forge sf-hamilton

This method installs the core library without visualization extras. To get visualization support, add matplotlib and networkx separately:

conda install -c conda-forge sf-hamilton matplotlib networkx

Then test the installation the same way:

import hamilton
print(hamilton.__version__)

Install in a virtual environment

It is good practice to use a virtual environment to avoid package conflicts. Create one with venv:

python -m venv hamilton_env
source hamilton_env/bin/activate   # On Windows: hamilton_env\Scripts\activate

Once the environment is active, install Hamilton:

pip install "sf-hamilton[visualization]"

Now Hamilton is isolated inside this environment. When you are done, deactivate with deactivate.

Install specific versions

Sometimes you need a specific Hamilton version for compatibility. Use pip with the version pin:

pip install "sf-hamilton[visualization]==1.60.0"

To see all available versions, run:

pip index versions sf-hamilton

Always check the PyPI page for release notes before pinning an older version.

Verify your installation

After installation, create a small test to confirm everything works. Write the following code in a file called test_hamilton.py:

# test_hamilton.py
import pandas as pd
from hamilton import driver

def raw_data() -> pd.DataFrame:
    """Return sample data."""
    return pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})

def processed(raw_data: pd.DataFrame) -> pd.DataFrame:
    """Add a column."""
    df = raw_data.copy()
    df["sum"] = df["x"] + df["y"]
    return df

if __name__ == "__main__":
    dr = driver.Driver({}, raw_data, processed)
    output = dr.execute(["processed"])
    print(output)

Run the script:

python test_hamilton.py

You should see output like this:

   x  y  sum
0  1  4    5
1  2  5    7
2  3  6    9

If you see the DataFrame, Hamilton is fully functional. If you get errors, check the troubleshooting section below.

Troubleshooting common issues

Sometimes installation fails. Here are the most common problems and fixes.

Problem:pip install sf-hamilton gives a "Could not find a version" error.

Solution: Upgrade pip first, then retry. If you are behind a corporate proxy, use pip install --proxy http://user:pass@proxy:port sf-hamilton.

Problem: Import fails with a DLL load failed on Windows.

Solution: Install the Microsoft C++ Build Tools. Hamilton depends on some compiled packages.

Problem: Visualization extra does not work.

Solution: Install matplotlib and networkx explicitly with pip install matplotlib networkx.

Conclusion

Installing the Hamilton dataflow framework in Python is straightforward. You can use pip or conda, and you should always work inside a virtual environment. After installation, run a small test to confirm everything works.

With Hamilton, you can build clean, maintainable data pipelines that are easy to test and debug. Now that you have it installed, start exploring its features like decorators, parallel execution, and integration with pandas or Spark.

Remember to keep your Hamilton version updated to benefit from new features and bug fixes. Happy dataflow building!