Guide · Open source

How to use SHAP: explain Python machine learning models

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

SHAP is a Python library for explaining why a machine learning model made a particular prediction. It uses Shapley values from game theory to give each input feature a share of credit relative to a baseline average. This guide shows you how to install it, create an explainer, and read the main plots, so you can explain single predictions and whole datasets.

SHAPshap/shap · ★ 25.8k · MIT Install options & downloads

Quick start

1Install SHAP. Run pip install shap, or conda install -c conda-forge shap if you use conda.
2Train or load a model. Use a supported model type, such as an XGBoost regressor or a Keras model.
3Create an explainer. Call shap.Explainer(model) for tree and transformers models, or shap.DeepExplainer for TensorFlow and Keras models.
4Compute SHAP values. Pass your data to the explainer to get shap_values.
5Plot one prediction. Use shap.plots.waterfall or shap.plots.force on a single row to see its feature contributions.
6Plot the whole dataset. Use shap.plots.beeswarm or shap.plots.bar to see which features matter most overall.

Install SHAP with pip or conda

SHAP can be installed from either PyPI or conda-forge. You need Python and either pip or conda. The README excerpt does not state a required Python version.

pip install shap
# or
conda install -c conda-forge shap

Enable GPU-accelerated Tree SHAP

To use GPU-accelerated Tree SHAP (GPUTreeExplainer), install the cuda extra. The README says this requires the CUDA toolkit to be installed on your system.

pip install shap[cuda]

Explain a tree model's predictions

Tree ensemble models such as XGBoost, LightGBM, CatBoost, scikit-learn and pyspark models get a fast, exact algorithm. Create an explainer from the trained model, then call it on your data. The base value is the average model output over the training data you pass in.

The waterfall plot shows features pushing the prediction higher in red and lower in blue, starting from the base value. The force plot shows the same explanation in another form.

Pass the trained model to shap.Explainer.
Call the explainer on your data to get shap_values.
Use shap.plots.waterfall or shap.plots.force on a single row, such as shap_values[0].

import xgboost
import shap

X, y = shap.datasets.california()
model = xgboost.XGBRegressor().fit(X, y)

explainer = shap.Explainer(model)
shap_values = explainer(X)

shap.plots.waterfall(shap_values[0])

See which features matter across a dataset

To see overall feature importance, use a beeswarm plot. It sorts features by the sum of SHAP value magnitudes over all samples and shows the spread of each feature's impact. Color shows the feature value, with red for high and blue for low.

A bar plot takes the mean absolute SHAP value for each feature. The README notes it produces stacked bars for multi-class outputs.

Beeswarm: distribution of impacts per feature.
Bar: mean absolute SHAP value per feature.
Scatter: effect of one feature, colored by another feature to show interactions.

shap.plots.beeswarm(shap_values)
shap.plots.bar(shap_values)
shap.plots.scatter(shap_values[:, "Latitude"], color=shap_values)

Explain text and deep learning models

SHAP has specific support for Hugging Face transformers pipelines. Pass a supported pipeline to shap.Explainer and plot the result with shap.plots.text. For TensorFlow models and Keras models using the TensorFlow backend, use shap.DeepExplainer with a set of background examples. The README says there is also preliminary support for PyTorch.

For image models, shap.image_plot shows the explanation for each output. Red pixels increase the model's output and blue pixels decrease it.

e = shap.DeepExplainer(model, background)
shap_values = e.shap_values(x_test[1:5])
shap.image_plot(shap_values, -x_test[1:5])

What people use it for

Explaining why a gradient-boosted model priced a house a certain way, using a waterfall plot.
Finding which features drive predictions across a full dataset with a beeswarm plot.
Seeing how one feature, such as latitude, changes model output across samples with a scatter plot.
Showing which pixels in an image push a Keras model's output up or down.
Learning model interpretability with the example notebooks included in the project.

Frequently asked questions

How do I install SHAP?

Run pip install shap to install from PyPI, or conda install -c conda-forge shap to install from conda-forge. For GPU-accelerated Tree SHAP, run pip install shap[cuda], which the README says requires the CUDA toolkit.

Is SHAP free to use?

SHAP is released under the MIT licence, according to the project listing. Check the LICENSE file in the repository for the full terms.

Which models does SHAP support?

SHAP can explain the output of any machine learning model. The README highlights fast exact support for XGBoost, LightGBM, CatBoost, scikit-learn and pyspark tree models, plus transformers pipelines and TensorFlow or Keras models.

Does SHAP work with PyTorch?

The README says there is preliminary support for PyTorch models in DeepExplainer. TensorFlow and Keras models are the main supported deep learning paths.

What is the difference between SHAP and LIME?

LIME is listed as a comparable project. SHAP uses Shapley values from game theory to assign feature credit relative to a baseline average. Compare the two on your own model, since the README does not benchmark them.

Do SHAP values prove that a feature causes the prediction?

No. The README states that SHAP describes attributions, not causal effects. Use the explanations to understand model behaviour, not to conclude causation.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

SHAP suits data scientists and analysts who write Python and need to explain tree-based or deep learning models, and students learning interpretability. It is a library, not an app, so it is a poor fit for anyone who wants a finished tool without coding. If you need causal conclusions or a no-code interface, pick a different tool.

Install options & downloads