Introduction

Determining the actual cause-and-effect relationships between variables in a dataset is often the most challenging part of data analysis. While traditional correlation-based methods only show that two variables move together, they cannot tell you if one causes the other. Causal-Learn is an open-source Python library that solves this by implementing a comprehensive suite of causal discovery algorithms, allowing researchers and data scientists to recover causal structures from observational data without requiring expensive interventional experiments. With a strong foundation in the work of the CLeaR group at Carnegie Mellon University, it provides a bridge between academic rigor and practical Python-based machine learning workflows.

What Is Causal-Learn?

Causal-Learn is a Python package for causal discovery that provides implementations of both classical and state-of-the-art algorithms to identify causal relationships in observational data. It is a Python translation and extension of the renowned Tetrad java code, designed to bring these sophisticated statistical methods to the Python ecosystem. Licensed under the MIT License, the project is maintained by the CLeaR group and focuses on providing provable correctness guarantees for the recovered causal graphs.

The library is built to be modular, offering not only high-level APIs for non-specialists but also low-level building blocks—such as independence tests and score functions—that allow developers to build their own custom causal discovery methods. This makes it a primary tool for anyone moving beyond simple correlation to actual causal inference.

Why Causal-Learn Matters

For years, the most powerful tools for causal discovery were locked behind Java (Tetrad) or R (pcalg, bnlearn). Python developers had to rely on wrappers or complex JPype installations to access these capabilities. Causal-Learn fills this gap by providing a native Python implementation, which aligns with the current preference for Python in the machine learning and data science communities. This removes the friction of cross-language dependencies and simplifies deployment in modern AI pipelines.

Beyond convenience, Causal-Learn is critical because it allows for the discovery of causal structures from observational data. In many real-world scenarios, such as healthcare or economics, performing a randomized controlled trial (RCT) is either impossible, unethical, or too expensive. Causal-Learn provides the mathematical framework to infer the direction of causality (e.g., does A cause B, or does B cause A?) from data that has already been collected, which is a fundamental shift in the move toward “Causal AI”

Key Features

• Constraint-Based Discovery: Implements algorithms like PC and FCI that use conditional independence tests to prune edges in a graph, effectively identifying the skeleton of the causal network.
• Score-Based Discovery: Features algorithms such as GES (Greedy Equivalence Search) that treat causal discovery as an optimization problem, searching for the graph that best fits the data based on a score (like BIC).
• Functional Causal Models: Provides methods based on constrained functional causal models, including LiNGAM (Linear Non-Gaussian Acyclic Model), which can identify the exact direction of causality in non-Gaussian data.
• Hidden Causal Representation Learning: Implements advanced methods to identify latent (hidden) variables that may be influencing the observed variables, preventing the “confounder” problem.
• Permutation-Based Methods: Includes tools like GRaSP and BOSS for discovering causal structures through the permutation of data samples.
• Granger Causality: Provides implementations of linear Granger causality to analyze time-series data and determine if one time series can predict the other.
• Independence Test Utilities: Offers a wide array of (conditional) independence tests, including the Fisher-z test and Kernel-based conditional independence (KCI) tests, which are the building blocks of most constraint-based algorithms.
• Graph Visualization: Integrates with matplotlib and graphviz to allow users to visualize the resulting causal Directed Acyclic Graphs (DAGs) and Completed Partially Directed Acyclic Graphs (CPDAGs).

How Causal-Learn Compares

Causal-Learn is often compared to other causal inference libraries like DoWhy or the original Tetrad framework. While DoWhy focuses more on causal estimation (answering “how much” a cause affects an outcome), Causal-Learn focuses on causal discovery (answering “what is the cause”).

The primary differentiator for Causal-Learn is its native Python implementation of the Tetrad algorithms. For users who need to integrate causal discovery into a scikit-learn or pandas pipeline, Causal-Learn is the most logical choice. However, it is worth noting that some users have reported that certain algorithms, like GES, may run slower in Python than in the original Java implementation of Tetrad. This is a known tradeoff of moving from a compiled language to a dynamic one.

Getting Started: Installation

Causal-Learn requires several scientific Python libraries to be installed. It is recommended to use a virtual environment to avoid dependency conflicts.

Prerequisites

Ensure you have Python 3.7 or higher installed. You will also need the following packages:

• numpy, networkx, pandas, scipy, scikit-learn, statsmodels, pydot
• For visualization, you must install matplotlib and graphviz.

Installation via PyPI

The simplest way to install Causal-Learn is via pip:

pip install causal-learn

Installation from Source

For those who wish to contribute or use the development version, you can install from the GitHub repository:

git clone https://github.com/py-why/causal-learn.git
cd causal-learn
pip install .

How to Use Causal-Learn

The basic workflow in Causal-Learn involves loading your data into a numpy array, selecting a discovery algorithm, and then visualizing the resulting graph. The library is designed to be intuitive, following a pattern similar to other machine learning libraries.

For a simple “Hello World” scenario, you would typically use the PC algorithm, which is the most common constraint-based method. You pass your data to the algorithm, and the algorithm returns a graph object that represents the causal relationships.

Once the algorithm has run, you the graph can be visualized using the built-in visualization utilities. This allows you to verify the causal directions and the edges between variables.

Code Examples

The following examples are based on the TestPC.py and TestGES.py implementations found in the repository’s test suite.

Example 1: Constraint-Based Discovery with PC

This example shows how to use the PC algorithm to discover the causal structure of a dataset.

from causallearn.search.ConstraintBased.PC import pc
from causallearn.utils.GraphUtils import GraphUtils
import numpy as np

# Sample data
data = np.random.randn(100, 3)

# Run the PC algorithm
cg = pc(data)

# Visualize the result
G = cg.G
print(G)
GraphUtils.draw_graph(G)

In this snippet, pc(data) performs the conditional independence tests to find the edges. The resulting cg object contains the graph G, which is a CPDAG (Completed Partially Directed Acyclic Graph).

Example 2: Score-Based Discovery with GES

This example demonstrates the use of the Greedy Equivalence Search (GES) algorithm for structure learning.

from causallearn.search.ScoreBased.GES import ges
from causallearn.utils.GraphUtils import GraphUtils
import numpy as np

# Sample data
data = np.random.randn(100, 3)

# Run the GES algorithm
CausalGraph = ges(data)

# Visualize the result
GraphUtils.draw_graph(CausalGraph.G)

Here, ges(data) searches for the graph that maximizes the BIC score, greedily adding or removing edges to optimize the fit to the data.

Real-World Use Cases

Causal-Learn is particularly powerful in scenarios where experimental data is unavailable or unavailable. It is used by researchers and data scientists in the following ways:

• Healthcare Analytics: A medical researcher can use Causal-Learn to identify if a specific biomarker is causing a disease or if both are caused by a hidden confounder (e.g., genetic predisposition). This prevents the mistake of treating a symptom rather than the cause.
• Econometrics: An economist can analyze observational data from different countries to determine if a higher minimum wage increases or without increasing unemployment. By discovering the causal graph, they can identify the correct adjustment sets for causal effect estimation.
• Industrial Process Optimization: An engineer can use the library to discover the causal relationships between sensor readings in a manufacturing plant. By identifying the causal drivers of a défaut, they can optimize the process without trial-and-error experimentation.
• Root Cause Analysis: In software engineering, an SRE can use Causal-Learn on system logs and metrics to discover the causal chain of a system failure, moving beyond simple correlation of error spikes.

Contributing to Causal-Learn

Causal-Learn is an open-source project and contributions are highly encouraged. Because the project is a translation of the Tetrad framework, contributors should be mindful of the mathematical foundations of the algorithms. If you find a bug or encounter unexpected behavior, the best way to contribute is to open an issue on GitHub.

To submit a pull request, developers should ensure that their changes pass the unit tests located in the tests/ directory. This is critical because causal discovery algorithms are mathematically sensitive; small changes in the implementation can lead to significantly different causal graphs. Ensure you follow the GitHub standard flow: fork the repo, create a branch, and submit a PR.

Community and Support

The primary hub for the community is the GitHub repository. Users can find support through GitHub Discussions and by opening issues for bug reports and bug fixes. The project is maintained by the CLeaR group at Carnegie Mellon University, which is one of the leading research groups in the causal discovery field.

For detailed tutorials and deeper dives into the algorithms, users should refer to the official causal-learn documentation. The documentation site provides a comprehensive guide to the search methods and the independence tests used by the library.

Conclusion

Causal-Learn is the most comprehensive Python library for causal discovery, providing a bridge between academic research and practical data science. For those who move beyond simple correlation and want to understand the why behind their data, Causal-Learn is the essential tool. While it is a native Python implementation, users should be aware of the performance tradeoff in larger datasets where the original Java-based Tetrad may be faster.

Causal-Learn is the right choice when you need a variety of state-of-the-art causal discovery algorithms in a native Python environment, and when your primary goal is recovering the causal structure of your data from observational records. Star the repo, try the quickstart, and join the community to move your analysis from correlation to causality.

Resources

• Causal-Learn GitHub Repository
• Official Causal-Learn Documentation
• Example Causal Datasets for Benchmarking