Install & Compatibility
Where this runs
tested against v0.49.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 18.0s · import 4.876s · 547MB
554MB installed
● package 554MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
shap.Explainer
✓ explainer = shap.Explainer(model, data)
✗ explainer = shap.TreeExplainer(model, data) # or other specific explainer for general use
As of v0.36.0+, `shap.Explainer` is the recommended unified interface; it attempts to infer the best explainer. Specific explainers like `shap.TreeExplainer` are still valid for performance on specific model types.
shap_values
✓ shap_values = explainer(data)
✗ shap_values = explainer.shap_values(data)
The `explainer` object is now callable and returns a `shap.Explanation` object. The `.shap_values()` method is part of the old API.
shap.plots.beeswarm
✓ shap.plots.beeswarm(shap_values)
✗ shap.summary_plot(shap_values, data)
`shap.plots.beeswarm` and other `shap.plots.*` functions are part of the new plotting API and expect `shap.Explanation` objects. `shap.summary_plot` is part of the legacy API and expects raw NumPy arrays.
This quickstart demonstrates how to use SHAP to explain an XGBoost classifier. It involves generating synthetic data, training a model, initializing the SHAP explainer (which automatically detects the model type), calculating SHAP values using the modern callable explainer API, and visualizing the feature impacts with a beeswarm plot. For interactive environments like Jupyter, `shap.initjs()` may be required for plot rendering.
import shap
import xgboost
import pandas as pd
from sklearn.datasets import make_classification
# Generate synthetic data
X, y = make_classification(n_samples=1000, n_features=10, n_informative=5, n_redundant=2, n_classes=2, random_state=42)
X = pd.DataFrame(X, columns=[f'feature_{i}' for i in range(X.shape[1])])
# Train an XGBoost model
model = xgboost.XGBClassifier(use_label_encoder=False, eval_metric='logloss', random_state=42)
model.fit(X, y)
# For Jupyter notebooks, uncomment the following line to enable JavaScript visualizations:
# shap.initjs()
# Create a SHAP Explainer (automatically infers TreeExplainer for XGBoost)
explainer = shap.Explainer(model, X)
# Calculate SHAP values for the dataset
shap_values = explainer(X)
# Visualize the global impact of features using a beeswarm plot
# This plot shows the distribution of SHAP values for each feature.
shap.plots.beeswarm(shap_values, max_display=10)
# To visualize an individual prediction (e.g., the first instance) with a waterfall plot:
# shap.plots.waterfall(shap_values[0])
Debug
Known issues
breakingSHAP v0.50.0 and later versions officially dropped support for Python 3.9 and 3.10. The library now requires Python 3.11 or newer.fixUpgrade your Python environment to 3.11 or a later compatible version.
affects: >=0.50.0
breakingThe SHAP API for calculating explanation values and plotting underwent a significant change around v0.36.0. The `explainer.shap_values(X)` method was replaced by making the `explainer` object directly callable (`explainer(X)`), returning a `shap.Explanation` object. Legacy plotting functions like `shap.summary_plot` were deprecated, and new plotting functions (e.g., `shap.plots.beeswarm`, `shap.plots.waterfall`) expect the `shap.Explanation` object. The `auto_size_plot` parameter was removed from `shap.summary_plot` in v0.46.0.fixUpdate your code to use the new `shap.Explainer` API (e.g., `explainer = shap.Explainer(model, data); shap_values = explainer(data)`) and use the `shap.plots.*` functions that accept `shap.Explanation` objects.
affects: >=0.36.0, especially >=0.46.0
gotchaWhile SHAP v0.46.0 added support for NumPy 2.0, some machine learning libraries that SHAP depends on (e.g., TensorFlow, SciPy, Scikit-learn, Pandas, Numba) might still have compatibility issues or explicit version pins that prevent them from working with NumPy 2.0. This can lead to dependency conflicts during installation or runtime errors if not managed carefully.fixCarefully manage your environment dependencies. If encountering issues, consider pinning NumPy to a version less than 2.0 (`numpy<2.0`) or ensuring all your ML dependencies explicitly support NumPy 2.0.
affects: >=0.46.0
gotchaFor large datasets or high-dimensional inputs, `shap.KernelExplainer` can be very slow due to its model-agnostic nature, requiring numerous model evaluations. For tree-based models (like XGBoost, LightGBM, CatBoost), `shap.TreeExplainer` is significantly faster and provides exact SHAP values.fixPrefer `shap.TreeExplainer` for tree-based models. For non-tree models, consider sampling your background data or using approximate explainers where appropriate for performance.
affects: All versions
breakingThe test script (and certain SHAP functionalities like `shap.TreeExplainer` when used with XGBoost models) explicitly requires the `xgboost` library. If `xgboost` is not installed in your environment, a `ModuleNotFoundError` will occur when attempting to import or use it.fixEnsure the `xgboost` library is installed in your Python environment by running `pip install xgboost`.
affects: All versions
breakingWhen using minimal Docker images like `python:*-alpine`, installing libraries with C/C++ extensions (such as `scikit-learn`, a common dependency for SHAP) may fail due to missing build tools (e.g., `gcc`, `g++`). These tools are required to compile the native code during installation.fixInstall necessary build tools in your Dockerfile (e.g., `apk add build-base python3-dev` for Alpine) or use a more complete base image (e.g., `python:*-slim-buster` or `python:*-debian`).
affects: All versions
Errors
Common errors & fixes
ImportError: cannot import name 'TreeEnsemble' from 'sklearn.ensemble._forest'
This error occurs when the installed shap library version is incompatible with your scikit-learn version, often due to shap expecting an older scikit-learn internal structure for tree models.
fixUpgrade shap to the latest version to ensure compatibility with your scikit-learn installation: `pip install --upgrade shap`.
ValueError: Expected 2D array, got 1D array instead:
SHAP explainers, especially for single samples, typically expect input data to be a 2D array (e.g., (1, n_features)), but a 1D array was provided.
fixReshape your input data for a single sample using `data.reshape(1, -1)` before passing it to the explainer.
ValueError: The background dataset must have at least one sample.
When initializing `shap.KernelExplainer`, the `data` argument (representing the background dataset) must be a 2D array with at least one sample, but an empty or improperly shaped array was provided.
fixProvide a representative background dataset (e.g., a subset of your training data) as a 2D NumPy array or Pandas DataFrame to the `shap.KernelExplainer` constructor: `explainer = shap.KernelExplainer(model.predict, X_train_subset)`.
AttributeError: 'list' object has no attribute 'mean'
This error occurs when `shap_values` is a list of arrays (typically for multi-output models), and you attempt to call a NumPy array method like `.mean()` directly on the list object instead of an individual array within it.
fixIf `shap_values` is a list, you must select a specific output index (e.g., `shap_values[0]`) before performing array operations: `shap_values[0].mean(axis=0)`.
Upgrade
Version history
0.52.0latest on PyPI · released May 28, 2026
Audit
Dependencies
numpyrequiredCore dependency for numerical operations, required by most explainers.
pandasoptionalCommonly used for data handling with tabular explainers and datasets.
scikit-learnoptionalFor training various machine learning models that SHAP can explain.
xgboostoptionalHighly optimized TreeExplainer is available for XGBoost models.
lightgbmoptionalHighly optimized TreeExplainer is available for LightGBM models.
matplotliboptionalRequired for generating SHAP plots.