Release notes

To see the latest changes that are due on the next release, see v0.45.0…master.


Released on 2024-03-08 - GitHub - PyPI

This is a fairly significant release containing a number of breaking changes.

What's Changed

Breaking changes

  • Dropped support for 3.8 in #3414
  • The type and shape of returned SHAP values has changed in some cases, to be consistent with model outputs. The returned type for models with multiple outputs changed from list to np.ndarray. by @CloseChoice in #3318
  • Removed deprecated feature_dependence parameters in TreeExplainer and LinearExplainer by @thatlittleboy in #3340
  • Removed deprecated alias for Coefficient by @connortann in #3511



.. plus a large number of documentation, testing and other maintenance updates by @CloseChoice , @yuanx749 , @LakshmanKishore and others.

New Contributors

Thank you to a number of new contributors for their contributions to this release! We are eager to grow the pool of maintainers, so please do get in touch if you are interested in being part of the team.

Full Changelog: v0.44.1...v0.45.0


Released on 2024-01-25 - GitHub - PyPI

Patch release to fix an issue with the display of force plots.


  • Fixed HTML issue affecting display of force plots by @CloseChoice in #3464
  • Fixed calculation of interactions values for catboost regressors by @CloseChoice in #3459
  • Update XGBoost parsing to use ubjson format, replacing deprecated binary format by @CloseChoice in #3345


  • Further improvements to documentation

Full Changelog: v0.44.0...v0.44.1


Released on 2023-12-07 - GitHub - PyPI

This release contains a number enhancements and bug fixes.

What's Changed




New Contributors

Full Changelog: v0.43.0...V0.44.0


Released on 2023-10-09 - GitHub - PyPI

What's Changed

This release contains a number of bug fixes and improvements.

Following the NEP 29 deprecation policy, this release drops support for python 3.7.

Breaking changes

  • Removed the deprecated Boston dataset by @thatlittleboy in #3316
  • The shape of Explanation.base_values has been standardised between different TreeExplainer models to always be of shape (N,) and not (N,1). By @thatlittleboy in #3121


  • Added additivity check to Pytorch DeepExplainer (activated by default) by @noxthot in #3265
  • Added flag to allow the printing of the mean SHAP value in the legend of a multi-output bar plot. By @101AlexMartin in #3062
  • Added heatmap and violin plot to top-level API by @connortann in #3157
  • Replaced all tqdm imports with by @owenlamont in #3199


  • Fixed segmentation faults on MacOS with lightgbm tests (with newer libomp versions) by @thatlittleboy in #3093
  • Support LightGBM ensemble containing single leaf trees (stump) by @thatlittleboy in #3094
  • Fixed conversion DataFrame to ndarray for by @danieleongari in #3131
  • Fixed waterfall plot on explanations of sklearn tree models by @connortann in #3138
  • Fixed pandas input for gradient explainer by @Koen-Git in #3153
  • Fixed slicing of feature_names in Explanation objects with square .values by @thatlittleboy in #3126
  • Correct xlim in force_matplotlib in cases where the signs of force are all the same by @zaburo-ch in #2839
  • Fixed ngboost explanations when col_sample < 1 by @CloseChoice in #3294
  • Fixed torch additivity check in PyTorch DeepExplainer by @noxthot in #3281
  • Replaced print statements with warnings in DeepExplainer by @znacer in #3264
  • Replace deprecated register_backward_hook() by @noxthot in #3259
  • Fixed deprecated use of xgboost early_stopping_rounds by @CloseChoice in #3306
  • Fixed 3rd party deprecation warnings: numba, xgboost, typing, distutils by @connortann in #3084
  • Updated the Javascript bundle to update deprecated dependencies by @connortann in #2974

There have also been a large number of improvements to the tutorials and examples, by @connortann, @znacer, @arshiaar, @thatlittleboy, @dsgibbons, @owenlamont and @CloseChoice

New Contributors

Full Changelog: v0.42.1...v0.43.0


Released on 2023-07-15 - GitHub - PyPI

Patch release to provide wheels for a broader range of architectures.



Full Changelog: v0.42.0...v0.42.1


Released on 2023-07-06 - GitHub - PyPI

This release incorporates many changes that were originally contributed by the SHAP community via @dsgibbons's Community Fork, which has now been merged into the main shap repository. PRs from this origin are labelled here as fork#123.

This will be the last release that supports python 3.7.







Released on 2022-06-16 - GitHub - PyPI

Lots of bugs fixes and API improvements.


Released on 2021-10-20 - GitHub - PyPI

This release contains many bugs fixes and lots of new functionality, specifically for transformer based NLP models. Some highlights include:

  • New plots, bug fixes, docs, and features for NLP model explanations (see docs for details).
  • important permutation explainer performance fix by @sander-sn
  • New joint scatter plots to plot many at once on the same y-scale
  • better tree model memory usage by @morriskurz
  • new docs by @coryroyce
  • new wheel building by @PrimozGodec
  • dark mode improvements for the docs by @gialmisi
  • api tweaks by @c56pony @nsorros @jebarb


Released on 2021-03-03 - GitHub - PyPI

Lots of new text explainer work courtesy of @ryserrao and serialization courtesy of @vivekchettiar! (will note all the other changes later)


Released on 2021-01-15 - GitHub - PyPI

Fixes a version mismatch with the v0.38.0 release and serialization updates.


Released on 2021-01-14 - GitHub - PyPI

This release contains improved support for explanations of transformer text models and support for the new Explanation object based API. Specific improvements include:

  • Transformer model support in the Text explainer courtesy of @ryserrao
  • Interventional Tree explainer GPU support courtesy of @RAMitchell
  • Image captioning model support courtesy of @anusham1990
  • Benchmarking improvements courtesy of @maggiewu19
  • New text and image visualizations courtesy of @vivekchettiar
  • New explainer serialization support courtesy of @vivekchettiar
  • Bug fixes for Linear explainer and the new API courtesy of @heimengqi
  • Fix for categorical plots courtesy of @jeffreyftang
  • CUDA support improvements courtesy of @JohnZed
  • Support for econML model courtesy of @vasilismsr
  • Many other bug fixes and API improvements.


Released on 2020-11-04 - GitHub - PyPI

This release contains more support for the new API, many bug fixes, and preliminary model agnostic text/image explainer support (still beta). Specific contributions include:

  • Fix Sampling explainer sample counting issue courtesy of @tcbegley
  • Add multi-bar plotting support.
  • Preliminary support for cohorts.
  • Fixed an import error courtesy of @suragnair
  • Fix Tree explainer issues with isolation forests with max_features < 1 courtesy of @zhanjiezhu
  • Huge documentation cleanup and update courtesy of @lrjball
  • Typo fix courtesy of @anusham1990
  • Added a documentation notebook for the Exact explainer.
  • Text and Image explainers courtesy of @anusham1990 and Ryan Serrao
  • Bug fix for shap.utils.hclust
  • Initial support for InterpretML EBM models.
  • Added column grouping functionality to Explainer objects.
  • Fix for loop index bug in Deep explainer for PyTorch courtesy of @quentinRaq
  • Initial text to text visualization concepts courtesy of @vivekchettiar
  • Color conversion warning fix courtesy of @wangjoshuah
  • Fix invertibility issues in Kernel explainer with the pseudoinverse courtesy of @PrimozGodec
  • New benchmark code courtesy of @maggiewu19 and @vivekchettiar
  • Other small bug fixes and enhancements.


Released on 2020-08-27 - GitHub - PyPI

This version contains a significant refactoring of the SHAP code base into a new (cleaner) API. Full backwards compatibility should be retained, but most things are now available in locations with the new API. Note that this API is still in a beta form, so refrain from depending on it for production code until the next release. Highlights include:

  • A new shap.Explainer object that auto-chooses the explainer based on the given model and masking dataset.
  • A new shap.Explanation object that allows for parallel slicing of data, SHAP values, base values (expected values), and other explanation-specific elements.
  • A new shap.maskers.* module that separates the various ways to mask (i.e. perturb/hide) features from the algorithms themselves.
  • A new shap.explainers.Partition explainer that can explain any text or image models very quickly.
  • A new shap.maskers.Partition masker that ensures tightly grouped features are perturbed in unison, so preventing "unrealistic" model inputs from inappropriately influencing the model prediction. It also allows for the exact quadratic time computation of SHAP values for the 'structured games' (with coalitions structured according to a hierarchical clustering).
  • A new shap.plots.* module with revamped plot types that all support the new API. Plots are now named more directly, so summary_plot (default) becomes beeswarm, and dependent_plot becomes scatter. Not all the plots have been ported over to the new API, but most have.
  • A new notebooks/plots/* directory given examples of how to use the new plotting functions.
  • A new function to directly create bar plots and also display hierarchical clustering structures to group redundant features together, and show the structure used by a Partition explainer (that relied on Owen values, which are an extension of Shapley values).
  • Equally check fixes courtesy of @jameslamb
  • Sparse kmeans support courtesy of @PrimozGodec
  • Pytorch bug fixes courtesy of @rightx2
  • NPM JS code clean up courtesy of @SachinVarghese
  • Fix logit force plot bug courtesy of @ehuijzer
  • Decision plot documentation updates courtesy of @floidgilbert
  • sklearn GBM fix courtesy of @ChemEngDataSci
  • XGBoost 1.1 fix courtesy of @lrjball
  • Make SHAP spark serializable courtesy of @QuentinAmbard
  • Custom summary plot color maps courtesy of @nasir-bhanpuri
  • Support string inputs for KernelSHAP courtesy of @YotamElor
  • Doc fixes courtesy of @imatiach-msft
  • Support for GPBoost courtesy of @fabsig
  • Import bug fix courtesy of @gracecarrillo and @aokeson


Released on 2020-02-27 - GitHub - PyPI

This release includes:

  • Better support for TensorFlow 2 (thanks @imatiach-msft)
  • Support for NGBoost models in TreeExplainer (thanks @zhiruiwang)
  • TreeExplainer support for the new sklearn.ensemble.HistGradientBoosting model.
  • New improved versions of PartitionExplainer for images and text.
  • IBM zOS compatibility courtesy of @DorianCzichotzki.
  • Support for XGBoost 1.0
  • Many bug fixes courtesy of Ivan, Christian Paul, @RandallJEllis, and @ibuda.


Released on 2019-12-27 - GitHub - PyPI

This release includes:

  • Many small bug fixes.
  • Better matplotlib text alignment during rotation courtesy of @koomie
  • Cleaned up the C++ transformer code to allow easier PRs.
  • Fixed a too tight check_additivity tolerance in TreeExplainer #950
  • Updated the LinearExplainer API to match TreeExplainer
  • Allow custom class ordering in a summary_plot courtesy of @SimonStreicher


Released on 2019-12-11 - GitHub - PyPI

This release contains various bug fixes and new features including:

  • Added PySpark support for TreeExplainer courtesy of @QuentinAmbard
  • A new type of plot that is an alternative to the force_plot, a waterfall_plot
  • A new PermutationExplainer that is an alternative to KernelExplainer and SamplingExplainer.
  • Added return_variances to GradientExplainer for PyTorch courtesy of @s6juncheng
  • Now we use exceptions rather than assertions in TreeExplainer courtesy of @ssaamm
  • Fixed image_plot transpose issue courtesy of @Jimbotsai
  • Fix color bar axis attachment issue courtesy of Lasse Valentini Jensen
  • Fix tensor attachment issue in PyTorch courtesy of @gabrieltseng
  • Fix color clipping ranges in summary_pot courtesy of @joelostblom
  • Address sklearn 0.22 API changes courtesy of @lemon-yellow
  • Ensure matplotlib is optional courtesy of @imatiach-msft


Released on 2019-11-06 - GitHub - PyPI

This release is just intended to push better auto-deploy bundles out of travis and appveyor.


Released on 2019-11-06 - GitHub - PyPI

This release includes:

  • Support for sklearn isolation forest courtesy of @JiechengZhao
  • New check_additivity tests to ensure no errors in DeepExplainer and TreeExplainer
  • Fix #861, #860
  • Fix missing readme example html file
  • Support for spark decision tree regressor courtesy of @QuentinAmbard
  • Better safe isinstance checking courtesy of @parsatorb
  • Fix eager execution in TF < 2 courtesy of @bottydim


Released on 2019-10-21 - GitHub - PyPI

This release contains several new features and bug fixes:

  • GradientExplainer now supports TensorFlow 2.0.
  • We now do a lazy load of the plotting dependencies, which means a pip install no longer needs to also pull in matplotlib, skimage, and ipython. This should make installs much lighter, especially those that don't need plotting :)
  • Added a new BruteForceExplainer for easy testing and comparison on small problems.
  • Added a new partial_dependence_plot function. This function will be used to illustrate the close connections between partial dependence plots and SHAP values in future example notebooks.
  • Handle the multiclass case with no intercept in LinearExplainer courtesy of @gabrieltseng
  • Some extras_require options during the pip install courtesy of @AbdealiJK
  • Other small bug fixes and updates


Released on 2019-10-09 - GitHub - PyPI

This release is primarily to remove a dependency on dill that was not in It also includes:


Released on 2019-09-09 - GitHub - PyPI

  • Fix floating point rounding mismatches in recent sklearn versions of tree models
  • An update to allow easier loading of custom tree ensemble models by TreeExplainer.
  • decision_plot documentation updates courtesy of @floidgilbert


Released on 2019-08-31 - GitHub - PyPI


Released on 2019-06-19 - GitHub - PyPI

  • Fixes an issue in DeepExplainer caused by a change in TensorFlow 1.14.


Released on 2019-06-19 - GitHub - PyPI

Various bug fixes and improvements including:

  • adding SHAP values for binary classification to CatBoost courtesy of @dvpolyakov
  • Integer division fix for plots courtesy of @pmeier-tiplu
  • Support passing in an Axes object to dependence_plot courtesy of @mqk
  • Add adaptive average pooling and conv transpose layers courtesy of of @gabrieltseng
  • fix import errors on a missing matplotlib backend courtesy of @hchandola
  • fix TreeExplainer GradientBoostingClassifier bug courtesy of @prempiyush
  • make tqdm play nicer with notebooks courtesy of @KOLANICH
  • Allow deep_pytorch to use cuda models courtesy of @juliusbierk
  • Fix sklearn GradientBoostingRegressor bug courtesy of @nasir-bhanpuri
  • adding sparse support to shap linear explainer courtesy of @imatiach-msft


Released on 2019-05-15 - GitHub - PyPI

Fixes to support changes in the most recent version of sklearn


Released on 2019-05-14 - GitHub - PyPI

A few contribution highlights of this release (in chronological order)

  • Better testing courtesy of @jorgecarleitao
  • Image plot customizations courtesy of @verdimrc
  • Batch norm support for PyTorch in DeepExplainer courtesy of @JiechengZhao
  • Leaky ReLU and other conv layer support for pytorch deep explainer courtesy of @gabrieltseng
  • Fixed keras multi input in gradient explainer and improved random seeds courtesy of @moritzaugustin
  • Support for catBoost ranker courtesy of @doramir
  • Added XGBRanker and LGBMRanker to TreeExplainer courtesy of @imatiach-msft
  • Fix embedding lookup with tf.keras in DeepExplainer courtesy of @andriy-nikolov
  • Custom dependence_plot colors maps courtesy of @rcarneva
  • Fix divide by zero issues possible with CatBoost models courtesy of @dvpolyakov
  • Lots of other bug fixes/improvements!


Released on 2019-02-16 - GitHub - PyPI

This release is just to refresh the Windows builds on AppVeyor that didn't complete for 0.28.4


Released on 2019-02-16 - GitHub - PyPI

  • Fixes memory corruption error from TreeExplainer (courtesy of @imatiach-msft)
  • Adds support for skopt Random Forest and ExtraTrees Regressors (courtesy of @Bacoknight)
  • Adds support for matplotlib forceplot with text rotation (courtesy of @vatsan)
  • Adds a save_html function


Released on 2019-01-24 - GitHub - PyPI

  • Fix some plot coloring issues introduced by 0.28 (such as #406)


Released on 2019-01-23 - GitHub - PyPI

  • Downgrade numpy API usage to support older versions.


Released on 2019-01-23 - GitHub - PyPI

  • Fixes a byte-alignment issue on Windows when loading XGBoost models.
  • Now matches tree_limit use in XGBoost models courtesy of @HughChen
  • Fix an issue with the expected_value of transformed model outputs in TreeExplainer


Released on 2019-01-21 - GitHub - PyPI

  • Add support for rank-based feature selection in KernelExplainer.
  • Depreciate l1_reg="auto" in KernelExplainer in favor of eventually defaulting to l1_reg="num_features(10)"
  • New color scales based on the Lch color space.
  • Better auto-color choices for multi-class summary plots.
  • Better plotting of NaN values in dependence_plots
  • Updates for Pytorch 1.0 courtesy of @gabrieltseng
  • Fix the sklearn DecisionTreeClassifier handling to correctly normalize to a probability output
  • Enable multi-output model support for TreeExplainer when feature_dependence="independent"
  • Correctly load the objective of LightGBM models for use in explaining the model loss.
  • Fix numerical precision mismatch with sklearn models.
  • Fix numerical precision mismatch with XGBoost models by now directly loading from memory instead of JSON.


Released on 2019-01-01 - GitHub - PyPI

  • Better hierarchal clustering orderings that now rotate subtrees to give more continuity.
  • Work around XGBoost JSON issue.
  • Account for NaNs when doing auto interaction detection.
  • PyTorch fixes.
  • Updated LinearExplainer.


Released on 2018-12-12 - GitHub - PyPI

  • Complete refactor of TreeExplainer to support deeper C++ integration
  • The ability to explain transformed outputs of tree models in TreeExplainer, including the loss. In collaboration with @HughChen
  • Allow for a dynamic reference value in DeepExplainer courtesy of @AvantiShri
  • Add x_jitter option for categorical dependence plots courtesy of @ihopethiswillfi
  • Added support for GradientBoostingRegressor with quantile loss courtesy of @dmilad
  • Better plotting support for NaN values
  • Fixes several bugs.


Released on 2018-11-09 - GitHub - PyPI

  • Allows ordering_keys to be given to force_plot courtesy of @JasonTam
  • Fixes sparse nonzero background issue with KernelExplainer courtesy of @imatiach-msft
  • Fix to support tf.concat in DeepExplainer.


Released on 2018-11-08 - GitHub - PyPI

Fixes a problem where tree_shap.h was not included in the pip bundle.


Released on 2018-11-07 - GitHub - PyPI

  • Support for PyTorch in GradientExplainer and preliminary support for PyTorch in DeepExplainer courtesy of @gabrieltseng.
  • A matplotlib version of the single sample force_plot courtesy of @jverre.
  • Support functional Keras models in GradientExplainer.
  • KernelExplainer speed improvements.
  • Various performance improvements and bug fixes.


Released on 2018-08-24 - GitHub - PyPI

New improvements include: Faster KernelExplainer execution for sparse inputs. Support for sklearn gradient boosting classifiers. DeepExplainer extended to support very deep models.


Released on 2018-08-16 - GitHub - PyPI

This fixes numerical stability issues with the softmax operator for DeepExplainer. It also fixes a minor alignment issue with image_plot.


Released on 2018-08-16 - GitHub - PyPI

This release includes a nice update courtesy of @imatiach-msft for KernelExplainer. KernelExplainer now runs faster and supports sparse data matrices!

We have also refactored DeepExplainer and made it compatible with TensorFlow 1.10. There are still a few issues to track down, but DeepExplainer is getting more complete :)


Released on 2018-08-09 - GitHub - PyPI

Fixes a problem with DeepExplainer on TensorFlow >= 1.9. Fixes a bar plotting issue.


Released on 2018-08-08 - GitHub - PyPI

Fix a pip packaging error with other explainers.


Released on 2018-08-08 - GitHub - PyPI

Fix an import error introduced in the last release when installing from pip.


Released on 2018-08-08 - GitHub - PyPI

Integrates the JS code from iml into shap to simplify dependencies. Adds support for more TensorFlow components in DeepExplainer. Refactors the plotting functions and removes some long-deprecated functions. Fixes an error in KernelExplainer when using a non-zero reference value (#192).


Released on 2018-07-24 - GitHub - PyPI

A new LinearExplainer that can estimate SHAP values for linear models while accounting for correlations among the input features.


Released on 2018-07-23 - GitHub - PyPI

Fixes some issues with categorical features in LightGBM. Also fixes some issues created by the v.20 API changes.


Released on 2018-07-17 - GitHub - PyPI

This is just a tag to get Window's wheel files built.


Released on 2018-07-17 - GitHub - PyPI

This release brings a significant interface change. The expected value of the model is no longer included as the last column of the returned shap_values array. Instead it can be accessed as explainer.expected_value. This should make things much cleaner going forward, since the shape of the shap_values matrix will now be exactly the same as the input array to the model. This is particularly important for deep learning models with many dimensional input tensors. Note that because of this change shap.force_plot() now requires the model's expected (base) value as the first argument.


Released on 2018-07-13 - GitHub - PyPI

Adds support for embedding layers and LSTM dropout among other things.


Released on 2018-07-12 - GitHub - PyPI

DeepExplainer now supports the TensorFlow components used by LSTM's.

V0.19.3: v0.19.3

Released on 2018-07-07 - GitHub - PyPI

Fully functional implementations of DeepExplainer and GradientExplainer now available.


Released on 2018-06-29 - GitHub - PyPI

Fixes an important bug when explaining sklearn models (#137).


Released on 2018-06-28 - GitHub - PyPI

This marks the final release before potential interface changes to support multi-dimensional inputs in DeepExplainer.