Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
DoWhy is an open-source Python library for causal inference that asks you to state your causal assumptions explicitly and then test them. You install it with pip install dowhy and work through four steps: model a causal graph, identify the effect, estimate it, and refute the estimate with robustness checks. It is maintained in the py-why GitHub organisation under the MIT license and is aimed at researchers who need an effect estimate from observational data and want the assumptions behind it written down.
What DoWhy is used for in research
The DoWhy README describes it as a Python library for causal inference that supports explicit modeling and testing of causal assumptions. In its own words, decision-making involves understanding how variables affect each other and predicting the outcome when some of them are changed, and DoWhy provides a unified interface for those causal questions. The paper that introduced it (Sharma and Kiciman, 2020) makes the design argument plainly: most libraries concentrate on estimators, whereas DoWhy puts the assumptions first.
In practice that means a typical research use looks like this. You have observational data with a treatment (an exposure, programme or intervention), an outcome, and a set of other measured variables. You encode what you believe about how those variables cause one another as a graph. DoWhy then works out whether the effect of the treatment on the outcome can be computed from the data given that graph, applies an estimator you choose, and runs checks that try to break the answer. The documentation defines the target quantity as the average causal effect E[Y | do(A)], and, for a subpopulation, the conditional average causal effect E[Y | do(A), X].
The library covers more than effect estimation. Its graphical causal model (GCM) module, described in the README and in Blöbaum and colleagues (2024), supports further causal questions such as attributing an observed anomaly to nodes in a system. This guide stays with the effect-estimation workflow, which is what most researchers searching for DoWhy need first. If you are still deciding whether a causal question can be asked of your data at all, start with the CASRAI guide to causal analysis, and for the difference between a causal effect and a mere association see spurious correlation.
How to install or access it
The README states that DoWhy supports Python 3.8+ and can be installed with pip, poetry or conda. The commands it gives are:
pip install dowhy(latest release from PyPI)poetry add dowhyconda install -c conda-forge dowhypip install git+https://github.com/py-why/dowhy@main(development version from GitHub)
Three optional components are worth knowing about before you start. If you want to supply graphs in DOT format, install pydot (or pygraphviz). For better-looking rendered graphs, install pygraphviz, which needs Graphviz installed first and, in the README’s words, can cause problems on some platforms. For conditional (subgroup) effects you can call methods from EconML, which is a separate package in the same py-why organisation. None of these is needed for the basic four-step example below.
The library is documented at pywhy.org/dowhy and the source is at github.com/py-why/dowhy. Use those two locations, and PyPI for release numbers, rather than copies of the code in tutorials, because the method names accepted by estimate_effect and refute_estimate are strings that must match the version you installed.
Step-by-step: estimate and test one causal effect
The official getting-started page generates a synthetic dataset and runs the four steps on it. Reproducing that example is the safest way to confirm your installation works before you point DoWhy at real data.
- Load data.
from dowhy import CausalModelandimport dowhy.datasets, thendata = dowhy.datasets.linear_dataset(beta=10, num_common_causes=5, num_instruments=2, num_samples=10000). Herebeta=10sets the true effect, so you know the correct answer in advance. - Model.
model = CausalModel(data=data['df'], treatment=data['treatment_name'], outcome=data['outcome_name'], graph=data['gml_graph']). The graph argument is where your assumptions live. The README notes a graph can be defined in different ways, most commonly as a NetworkXDiGraph, and the sample passes a GML string. - Identify.
identified_estimand = model.identify_effect(). This asks whether the effect can be expressed in terms of observed quantities, given the graph. The user guide lists four identification algorithms: backdoor, frontdoor, instrumental variable and the ID algorithm. - Estimate.
estimate = model.estimate_effect(identified_estimand, method_name='backdoor.propensity_score_matching'). The method name is the identification strategy and the estimator joined by a dot. - Refute.
refute_results = model.refute_estimate(identified_estimand, estimate, method_name='random_common_cause'). Print the result object to read it.
For real data you replace step 1 with your own pandas DataFrame and name the treatment and outcome columns. The graph is the part that cannot be automated away. The DoWhy documentation says the causal graph must be a directed acyclic graph, where an edge X to Y means X causes Y, and calls the graph the most important component of most causal tasks because the accuracy of everything downstream depends on it. Drawing and checking that graph is covered in the CASRAI guides on DAGitty and on directed acyclic graphs and confounder selection; you can build the graph there and pass it to DoWhy as GML or DOT.
Choosing an estimator: identification strategy to class name
Because identification comes before estimation, the choice of estimator is constrained by what step 3 found. The user guide groups the average-effect estimators by the idea behind them. The table below restates that grouping with the class names, so you can match what identify_effect returned to a method you can legitimately call. The full machine-readable version is in the data table at the end of the page.
| Family (per the user guide) | Estimator classes |
|---|---|
| Matching on confounder values | DistanceMatchingEstimator |
| Modeling treatment assignment | PropensityScoreStratificationEstimator, PropensityScoreMatchingEstimator, PropensityScoreWeightingEstimator (inverse propensity weighting) |
| Modeling the outcome | LinearRegressionEstimator, GeneralizedLinearModelEstimator (including logistic regression) |
| Instrumental variable equation | InstrumentalVariableEstimator (binary instrument, Wald), RegressionDiscontinuityEstimator |
| Front-door criterion and mediation | TwoStageRegressionEstimator (two-stage linear regression) |
For conditional effects, the user guide says DoWhy supports calling EconML methods, and that a linear regression can also be used if the outcome can be approximated as a linear function. For the statistics behind the propensity-based options see propensity score matching explained, and for the instrumental-variable route see instrumental variables and weak-instrument diagnostics.
Output and how to read it
The README says DoWhy stresses the interpretability of its output: at any point you can inspect the untested assumptions, the identified estimands (if any) and the estimate (if any). Reading the output therefore means reading three things in order, not only the final number.
Read the identified estimand first
Printing the identified_estimand shows which identification strategy was found and the assumptions that strategy relies on. If no strategy applies, the effect is not identified from this graph and data, and no estimator can fix that. Change the graph (only if your domain knowledge supports the change), measure more variables, or reconsider the question.
Then the estimate
The estimate object reports the effect on the scale of the outcome for the method you called. In the synthetic example the true effect is 10, so a good estimate should land close to 10. On real data there is no known answer, which is why the refutation step exists.
Then the refutation
The user guide is explicit that a causal analysis based on observational data cannot be proved correct, but can be tested for failure with robustness checks, and that an analysis failing any one of the tests is incorrect and needs to be fixed. The same page notes the tests can rank competing estimation methods: choose the procedure that fails the fewest. Two of the refuters have a stated expected result:
- Placebo treatment refuter. It asks what happens to the estimated effect when the true treatment is replaced with an independent random variable. The documentation’s hint is that the effect should go to zero. The documented example uses
method_name='placebo_treatment_refuter'withplacebo_type='permute'. - Random common cause refuter. It asks whether the estimate changes after an independent random variable is added to the data as a common cause. The documentation’s hint is that it should not change.
The documentation also lists refuters that add a dummy outcome, take data subsamples, and run sensitivity analysis. Passing refutations does not prove the graph correct. The documentation states the same limit for graph refutation, which can only check necessary properties that any valid graph for the dataset should satisfy.
Worked example: what a failed check tells you
This is an illustrative composite, not a report of a real study. Suppose a researcher models a programme (treatment) and a later score (outcome) with age and baseline score as common causes, estimates a large positive effect by propensity score matching, and then runs the placebo treatment refuter. If the placebo effect also comes out clearly away from zero, the documented expectation (effect goes to zero) is violated. The right response is to treat the original estimate as unreliable, not to report it with a caveat. Typical places to look next are the graph (a missing common cause), the choice of estimator for the identified estimand, and the data preparation, and then to re-run the whole sequence. Whichever you change, the documented logic is the same: an analysis that fails a test needs to be fixed before the number is used.
Troubleshooting
- conda reports “Solving environment” problems. The README suggests running
conda update --alland installing again, thenconda config --set channel_priority falseif that fails. - A dependency fails to install. The README advises installing the dependencies manually with
pip install '(dependency-name)==(version)'. - You cannot read a DOT graph. Install
pydotorpygraphviz, as the README says for DOT input. - pygraphviz will not build. Install Graphviz first, then pygraphviz. The README gives Ubuntu and Ubuntu WSL commands and warns of problems on some platforms. It is optional, so skip it if you do not need rendered graphs.
- A method name is rejected. Method names are version-specific strings. Compare yours with the documentation for the exact release you installed.
Free alternatives and companions
DoWhy is not the only software for causal questions, and it is not designed to replace its neighbours. The two packages named in the sources as interoperating with it are below, together with the graph tool on this site.
| Tool | Relationship to DoWhy (as stated by the sources) |
|---|---|
| EconML | DoWhy can call EconML methods for conditional average treatment effects, for example backdoor.econml.dml.DML. It sits in the same py-why organisation. |
| CausalML | The DoWhy paper states that DoWhy interoperates with EconML and CausalML estimators. |
| DAGitty | A separate tool for drawing and analysing the causal graph, which you can then use as the DoWhy graph input. |
How to cite DoWhy
The README asks users to cite both of its papers: Sharma and Kiciman, “DoWhy: An End-to-End Library for Causal Inference” (arXiv:2011.04216, 2020), for the effect-estimation workflow, and Blöbaum, Götz, Budhathoki, Mastakouri and Janzing, the DoWhy-GCM paper in the Journal of Machine Learning Research, volume 25, issue 147 (2024), for the graphical causal model module. Report the DoWhy version you used and the exact method names, since both affect the result.
Frequently asked questions
What is DoWhy used for?
DoWhy is used to estimate causal effects from data while making the causal assumptions explicit and testable. It follows four steps (model, identify, estimate, refute) and also includes graphical causal model tools for other causal questions.
Is DoWhy free?
It is open source under the MIT license, according to its GitHub repository.
Which Python version does DoWhy need?
The README states Python 3.8+. Check the PyPI page for the release you install, since supported versions change between releases.
Do I need a causal graph?
The getting-started example passes a graph to CausalModel, and the documentation calls the graph the most important component of most causal tasks. The graph must be a directed acyclic graph where an edge X to Y means X causes Y.
Does passing the refutation tests prove my estimate is right?
No. The documentation says an analysis of observational data cannot be proved correct, only tested for failure. An estimate that fails any test needs to be fixed.
How is DoWhy different from EconML?
DoWhy covers modeling, identification, estimation and refutation. EconML supplies estimators, and DoWhy can call them, for example for conditional effects.
Sources
- DoWhy GitHub repository and README, py-why/dowhy, https://github.com/py-why/dowhy, checked 2026-11-14.
- DoWhy documentation, Getting started (v0.12), https://www.pywhy.org/dowhy/v0.12/getting_started/index.html, checked 2026-11-14.
- DoWhy user guide, Estimating causal effects (v0.12), https://www.pywhy.org/dowhy/v0.12/user_guide/causal_tasks/estimating_causal_effects/index.html, checked 2026-11-14.
- DoWhy user guide, Refuting causal estimates, placebo treatment and random common cause refuters (v0.12), https://www.pywhy.org/dowhy/v0.12/user_guide/causal_tasks/refuting_causal_estimates/index.html, checked 2026-11-14.
- DoWhy user guide, Modeling causal relations (v0.12), https://www.pywhy.org/dowhy/v0.12/user_guide/modeling_causal_relations/index.html, checked 2026-11-14.
- Sharma, A. and Kiciman, E. DoWhy: An End-to-End Library for Causal Inference, arXiv:2011.04216, https://arxiv.org/abs/2011.04216, checked 2026-11-14.
Data: DoWhy average-effect estimator classes grouped by method family
Compiled from the DoWhy v0.12 user guide page on estimating causal effects: each estimator class named there, the method family the guide places it in, and the target quantity it is listed under. Conditional effects are handled through EconML or linear regression per the same page.
Period covered: DoWhy v0.12 documentation.
| Estimator class | Method family (per user guide) | Target effect |
|---|---|---|
| DistanceMatchingEstimator | Matching on confounders' values | Average causal effect |
| PropensityScoreStratificationEstimator | Estimating treatment assignment (propensity-based stratification) | Average causal effect |
| PropensityScoreMatchingEstimator | Estimating treatment assignment (propensity score matching) | Average causal effect |
| PropensityScoreWeightingEstimator | Estimating treatment assignment (inverse propensity weighting) | Average causal effect |
| LinearRegressionEstimator | Estimating the outcome model (linear regression) | Average causal effect; also conditional effect if outcome approximately linear |
| GeneralizedLinearModelEstimator | Estimating the outcome model (generalized linear models, including logistic regression) | Average causal effect |
| InstrumentalVariableEstimator | Instrumental variable equation (binary instrument, Wald estimator) | Average causal effect |
| RegressionDiscontinuityEstimator | Instrumental variable equation (regression discontinuity) | Average causal effect |
| TwoStageRegressionEstimator | Front-door criterion and mediation (two-stage linear regression) | Average causal effect |
Sources
- DoWhy user guide: Estimating causal effects (v0.12) (accessed 2026-11-14)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







