causal-learn for Causal Discovery in Python

What causal-learn solves

causal-learn addresses the problem of estimating causal structure from observational data. The README says its goal is to recover relationships among variables without requiring interventional experiments, while offering algorithms with provable correctness guarantees. The intended users are Python researchers and practitioners working with causal discovery, including people who need more than a single estimator or want to assemble a custom method.

The package covers several distinct approaches. It includes constraint-based methods, score-based methods, methods based on constrained functional causal models, hidden causal representation learning, permutation-based discovery, and Granger causality. It also supplies supporting components such as independence tests, score functions, graph operations, and evaluations. This breadth matters because causal discovery is not one operation. A method suitable for one dataset may not match a nonlinear dataset, temporal observations, or a problem involving hidden variables.

The README describes causal-learn as a platform rather than a single application. That distinction makes it more useful as a research library, but it also means the package does not define a universal causal answer for every dataset. The user still has to select an algorithm, provide data in the form that algorithm expects, and interpret the resulting graph.

Architecture and data flow

The repository layout places the Python implementation under `causallearn/`, tests under `tests/`, documentation under `docs/`, and packaging metadata in `setup.py`. The package exposes implemented algorithms through Python modules, while the tests include examples for search methods and unit tests for supporting components such as conditional independence tests.

A typical causal discovery workflow begins with observational variables. A chosen algorithm analyzes relationships among those variables and returns a graph representation. Causal-learn includes graph operations and visualization dependencies, including `networkx`, `pydot`, `graphviz`, and `matplotlib`, but the README does not prescribe one mandatory graph-output format. The exact data preparation and return object therefore depends on the selected module and should be checked in its documentation or test.

The library's extension points are as important as its built-in estimators. The repository provides utilities for independence testing and score functions, so a researcher can study or replace parts of a discovery procedure. That is different from treating causal discovery as a command-line black box. It is convenient for experimentation, although it transfers more responsibility to the caller.

Install and start with the documented examples

The README specifies Python 3.7 or later and lists `numpy`, `networkx`, `pandas`, `scipy`, `scikit-learn`, `statsmodels`, and `pydot` as packages that must be installed beforehand. It also identifies `matplotlib` and `graphviz` for visualization. The package installation command is:

pip install causal-learn

`setup.py` additionally lists `tqdm`, `momentchi2`, and `joblib` in `install_requires`, so an environment resolver may install dependencies that are not called out in the README's short prerequisite list. The declared package version in `setup.py` is `0.1.4.8`.

After installation, the README points users to the documentation for detailed tutorials and usage. For a first project-specific use, inspect `tests/TestPC.py` and `tests/TestGES.py`. These files are identified as examples for search-based causal discovery. The repository does not provide a complete command-line invocation or a single copy-and-paste PC or GES example in the README, so an exact API call cannot be reproduced from the README alone. The documentation linked from the README is the source to consult for the current call signature and input format.

Supported algorithm families and their boundaries

Causal-learn's method list is broad, but broad coverage is not the same as interchangeable behavior. Constraint-based methods use independence information to restrict possible graph structures. Score-based methods compare structures using score functions. Constrained functional causal models approach the problem through assumptions about the data-generating process. Permutation-based methods use ordering information, Granger causality addresses temporal dependence, and hidden causal representation learning targets latent structure.

These categories require different inputs and carry different assumptions. The README does not document the precise assumptions, parameter choices, or data restrictions for each implemented algorithm. It also does not claim that every algorithm is suitable for observational data of the same dimensionality, noise pattern, or sampling design. A caller should therefore avoid choosing a method by algorithm name alone.

Granger causality is a particularly clear boundary. The package lists it as a supported method, but the README does not say that it should be interpreted as general causal identification or that its assumptions cover all temporal processes. Similarly, hidden causal representation learning addresses a different output from ordinary graph discovery. The library gives access to these approaches, but interpretation remains tied to the selected method.

Limitations and failure modes

The main limitation is stated by the problem itself: causal-learn is designed to work from observational data, while causal conclusions depend on assumptions about the data-generating process. The README does not provide a guarantee that an estimated graph will be correct for every dataset, nor does it offer a universal procedure for checking confounding, missing variables, selection effects, or measurement error.

A second limitation is discoverability. The README names algorithm families and points to tests and documentation, but it does not present a decision table that maps a dataset or research question to a specific estimator. Users may need to read the linked documentation and inspect the relevant tests before they can determine which module accepts their data.

The repository is not archived, and its last push was on 2026-09-04. That indicates repository activity, but it does not by itself validate a particular algorithm, dependency set, or upgrade. Version changes may affect the package API, so projects that depend on `0.1.4.8` should review release changes when upgrading. The MIT license permits use and modification under its terms, but the license does not resolve methodological or data-quality questions.

causal-learn compared with py-tetrad

The README itself points to `py-tetrad` as an alternative path for users who need arbitrary Java code from the classical Tetrad program inside a Python workflow. The difference is architectural and procedural. causal-learn provides Python implementations for many causal discovery algorithms and keeps the workflow within a Python package. py-tetrad is presented as a way to reuse the larger Tetrad Java codebase from Python.

That distinction can matter when a project needs a Tetrad algorithm or Java customization that causal-learn does not provide. It also introduces a boundary between the Python and Java environments. causal-learn is the more direct option when its implemented methods and utilities fit the task; py-tetrad is the more relevant option when access to Tetrad's broader Java implementation is the requirement. The README does not claim that either project covers every algorithm or that their outputs are interchangeable.

Editorial conclusion

causal-learn is a sensible choice for research workflows that need Python access to several causal discovery families and custom utilities. It is a poor fit for users who require a fully automatic, assumption-free answer or need methods that are not implemented in the package. Before adoption, verify the algorithm's assumptions against the data, inspect the relevant tests and documentation, and confirm that the required Python and scientific dependencies fit the intended environment.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. py-why/causal-learn on GitHub
4. README
5. Releases