---

Causal Inference for Quasi-Experiments in Python

Research-grade causal inference workflows for quasi-experimental designs in Python.

CausalPy helps you estimate causal effects with transparent assumptions, uncertainty-aware modeling, and reproducible outputs:

• Quasi-experimental methods: Difference-in-differences, synthetic control, regression discontinuity, interrupted time series, instrumental variables, and more
• Bayesian-first estimation via PyMC with full uncertainty quantification, plus traditional OLS via scikit-learn
• Decision-ready outputs: Effect summaries with credible intervals (HDI), practical significance (ROPE), and publication-quality plots

📞 Book a consulting call

CausalPy is built and maintained by PyMC Labs. If your team is exploring a consulting engagement for lift testing, complex or high-stakes causal work, you can book an introductory call. These calls are for consulting inquiries only. For technical usage questions and free community support, please use GitHub Discussions and the documentation below.

Help and documentation

• Ask usage questions in GitHub Discussions Q&A so the issue tracker stays focused on bugs and enhancements.
• Report bugs and feature requests in Issues
• Browse detailed guides in the documentation

Installation

To get the latest release:

pip install CausalPy

or via conda:

conda install causalpy -c conda-forge

Alternatively, if you want the very latest version of the package you can install from GitHub:

pip install git+https://github.com/pymc-labs/CausalPy.git

Runtime notes

As of the PyMC 6 release, CausalPy runs on PyMC 6 / PyTensor 3 / ArviZ 1.x and requires Python 3.12+. A few runtime behaviours are worth knowing about:

• numba is now a (transitive) hard dependency and the default backend. PyTensor 3 compiles models with numba by default, so the first sample from a freshly defined model incurs a noticeable one-off compilation delay before sampling starts. Subsequent samples reuse the compiled function.
• Native crashes can replace Python tracebacks. When a numba-compiled sampler worker dies, the failure may surface as a native crash or a stalled worker rather than a Python traceback — so a wedged worker can present as a silent hang rather than an exception.
• Installing nutpie changes sampling defaults. If a recent enough nutpie is installed, PyMC uses it as the default NUTS sampler unless you pass an explicit nuts_sampler=, and nutpie applies its own number of tuning steps rather than PyMC's built-in default of 1000. Merely installing nutpie is therefore enough to change how pm.sample() behaves; pass nuts_sampler="pymc" if you need the built-in sampler.

For the full list of breaking changes in this release, see the GitHub release notes.

AI Agent Skills

CausalPy includes agent skills that teach AI coding assistants how to use the library for causal inference. Skills are available via Decision AI Hub and live in causalpy/skills/ in the source tree.

Quickstart

import causalpy as cp
import matplotlib.pyplot as plt

# Import and process data
df = (
    cp.load_data("drinking")
    .rename(columns={"agecell": "age"})
    .assign(treated=lambda df_: df_.age > 21)
)

# Run the analysis
result = cp.RegressionDiscontinuity(
    df,
    formula="all ~ 1 + age + treated",
    running_variable_name="age",
    model=cp.pymc_models.LinearRegression(),
    treatment_threshold=21,
)

# Visualize the causal effect at the threshold
fig, ax = result.plot()

# Get a results summary with posterior estimates
result.summary()

The result.plot() visualizes the regression discontinuity design, showing the estimated jump at the treatment threshold. The result.summary() prints posterior estimates of the causal effect with uncertainty intervals.

Videos

Click on the thumbnail below to watch a video about CausalPy on YouTube.

When CausalPy is a good fit

• You have a plausible quasi-experimental design (threshold rule, policy change, staggered rollout, geo lift, etc.)
• You want uncertainty-aware estimates and diagnostics, not only point estimates
• You need reproducible analysis artifacts for review and communication

When CausalPy is not a fit

• You need causal discovery from weakly identified observational data
• You want fully automated "black box" causal answers without specifying assumptions
• You primarily need production workflow tooling (pipelines, governance, multi-user collaboration)

Methods and Workflows

CausalPy provides methods for common causal inference decision contexts:

Available methods

Diagnostics-first by design

CausalPy emphasizes transparent, uncertainty-aware outputs for rigorous causal analysis:

• Effect summaries: Every experiment provides effect_summary() returning decision-ready statistics with both tabular and prose formats
• Uncertainty quantification: Bayesian models report HDI (Highest Density Intervals); OLS models report confidence intervals
• Practical significance: ROPE (Region of Practical Equivalence) analysis to assess whether effects exceed meaningful thresholds
• Direction testing: Tail probabilities (e.g., P(effect > 0)) for directional inference

Citing CausalPy

If you use CausalPy in your research, please cite it. A Zenodo DOI for stable releases is planned. In the meantime, you can cite the repository:

@software{causalpy,
  author = {{PyMC Labs}},
  title = {CausalPy: Causal inference for quasi-experiments in Python},
  url = {https://github.com/pymc-labs/CausalPy},
  year = {2026}
}

Roadmap

Plans for the repository can be seen in the Issues.

License

Apache License 2.0

Thanks to our contributors

The contributor image is regenerated weekly by a GitHub Actions workflow (.github/workflows/contributors.yml) that opens a PR when the contributor list changes.