Installation#

Installation with conda or pip is recommended. Developers can follow the Install from source instructions below. If building from source, consider doing so within a conda environment and then exporting the environment for reproducibility.

To use models under the inference.tf, inference.torch or inference.jax module (e.g. DragonNet or CEVAE), additional dependency of tensorflow, torch or jax is required. For detailed instructions, see below.

System Requirements#

Python Version: Python 3.11 or later is required.

Linux Distributions: Pre-built binary wheels require a Linux distribution with glibc 2.28 or later:

  • Ubuntu: 20.04 LTS or later

  • RHEL/CentOS: 8 or later

  • Debian: 10 (Buster) or later

  • Fedora: 32 or later

Note

For older Linux distributions (e.g., RHEL 7, Ubuntu 16.04, Ubuntu 18.04), you will need to build CausalML from source. See Install from source below.

macOS and Windows: All recent versions are supported.

Note

On macOS, xgboost and lightgbm require the OpenMP runtime (libomp), which is not included by default. Without it, importing CausalML modules that use XGBoost can fail when the XGBoost native library cannot be loaded. Install it via Homebrew:

brew install libomp

or via conda-forge:

conda install -c conda-forge llvm-openmp

Install using conda#

Install conda#

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b
source miniconda3/bin/activate
conda init
source ~/.bashrc

Install from conda-forge#

Directly install from the conda-forge channel using conda.

conda install -c conda-forge causalml

Install from PyPI#

pip install causalml

Install causalml with tensorflow for DragonNet from PyPI#

pip install causalml[tf]

Install causalml with torch for CEVAE from PyPI#

pip install causalml[torch]

Install causalml with jax for DragonNet or CEVAE from PyPI#

pip install causalml[jax]

Install using uv#

uv init
uv add causalml

Install causalml with tensorflow for DragonNet using uv#

uv add "causalml[tf]"

Install causalml with torch for CEVAE using uv#

uv add "causalml[torch]"

Install causalml with jax for DragonNet or CEVAE using uv#

uv add "causalml[jax]"

Install from source#

[Optional] If you don’t have Graphviz installed, you can install it using conda, brew (on MacOS), or apt (on Linux).

conda install python-graphviz
brew install graphviz           # MacOS
sudo apt-get install graphviz   # Linux

First, clone the repository and install the package:

git clone https://github.com/uber/causalml.git
cd causalml
pip install -e .

with tensorflow for DragonNet:

pip install -e ".[tf]"

with torch for CEVAE:

pip install -e ".[torch]"

with jax for DragonNet or CEVAE:

pip install -e ".[jax]"

Windows#

See content in uber/causalml#678

Running Tests#

Make sure pytest is installed before attempting to run tests.

pip install -e ".[test]"

Run all tests with:

pytest -vs tests/ --cov causalml/

Add --runtf, --runtorch and/or --runjax to run optional tensorflow/torch/jax tests which will be skipped by default.

You can also run tests via make:

make test