Shapash: A Wrapper Around SHAP and LIME That Turns Model Explanations Into a Shareable Web App

The gap Shapash fills is not explanation, it is delivery

SHAP and LIME already produce explanations. What they do not produce is something a risk analyst, a product owner or an auditor can open in a browser and click through without writing Python. Shapash targets that gap. The README describes the library as designed to make machine learning interpretable and comprehensible for everyone, and the concrete artifact behind that claim is a web app that lets a reader move between local and global explainability without leaving the page.

The intended user is a data scientist who has to defend a model to people who did not build it. That is a narrower audience than the explainability topic suggests. If you are the only consumer of your explanations, you do not need Shapash at all; you need shap_values and a plotting call. The library earns its place when the explanation has to survive being handed to someone else, and when that someone else needs to filter by segment, inspect a single prediction, and see the aggregate picture in the same session.

What compile() actually assembles

The central object in Shapash is the explainer, and the central method is compile. According to the README, version 2.0.x refactored the attributes of the compile method and the init, and refactored the implementation to accommodate new backends. That refactor is the architectural fact that matters: Shapash does not implement Shapley values or surrogate models itself. It selects a backend, computes contributions through it, and then holds the results in a structure that the plotting layer and the web app both read from.

Supported model families listed in the README are Catboost, Xgboost, LightGBM, Sklearn ensembles, linear models and SVM, covering regression, binary classification and multiclass problems. For anything outside that list, the README points to integration solutions rather than claiming universal coverage. The data flow is therefore: fit your model in whatever framework you already use, hand the fitted model plus training data to the Shapash explainer, call compile, and from that point the contributions are cached in the explainer and reused by every downstream chart and by the app. That caching is why the app can respond to a click on a single row without recomputing the full explanation set.

Getting from a fitted model to a running app

The README does not print a full code block, so the exact constructor signature is not something I can quote from the supplied material. What it does establish is the shape of the workflow: an explainer is instantiated with the model and data, compile is called, and then the web app is launched from the explainer. The tutorial notebooks in the repository are the authoritative source for the precise argument names, and the overview notebook is named tutorial01-Shapash-Overview-Launch-WebApp.ipynb, which tells you where to start.

On the app side, the feature set added across 2.2.x and 2.3.x is documented in the changelog table. Version 2.2.x added a dataset filter tab and a picking samples tab whose graph plots true values against predicted values. Version 2.3.x added the ability to attach extra dataset columns, including target and error columns, and to add features that are not inputs to the model so that the app can filter on them. It also added an identity card summarizing the selected sample. If you are evaluating Shapash for a reporting use case, those extra columns are the feature to check first, because they determine whether the app can answer questions like which segment this prediction belongs to without a separate join.

The web app is the product, and that is also the constraint

Every feature highlighted in the changelog table lives inside the web app: additional columns, the identity card, sample picking, dataset filtering. Nothing in the listed recent releases points to improvements in the programmatic API for consuming explanations in code. That asymmetry is the honest summary of the project's priorities. Shapash is a presentation layer with an explainability engine attached, not an explainability engine with a viewer attached.

The practical consequence is a memory and startup constraint. The app holds the compiled explanations for the dataset you passed in, and the filtering and sample-picking tabs operate over that in-memory set. The documentation does not state a size limit, and I cannot give you one. What can be said is that the design implies you should compile against a representative sample rather than your full training set, and that this decision belongs to you, not to the library. Teams that pass a large frame and then wonder why the app is slow have made a choice the documentation did not make for them.

Where Shapash is the wrong tool

Three cases. First, automated monitoring. If you want to compute contribution drift on every scoring batch and write it to a warehouse, Shapash adds a presentation layer you will never render. Use the underlying explainer directly. Second, unsupported model types without a custom backend. The README is explicit that other models need integration work, and that work is on you. Third, any setting where the explanation must be reproducible to the decimal across environments. Shapash wraps SHAP and LIME, and both have their own versioning and their own approximation behaviour. The README itself links an article titled Building confidence on explainability methods, which suggests the maintainers treat explainer stability as a topic worth its own discussion rather than a solved property of the library.

There is also a language constraint worth naming. The primary language of the repository is Jupyter Notebook. That means a large share of the material you will read to learn the library is notebook tutorials rather than reference documentation. Tutorials are good for the first hour and poor for looking up a parameter six months in. The ReadTheDocs site exists and is linked prominently, but the repository's centre of gravity is the tutorial directory.

Shapash versus calling SHAP directly

The real alternative is not another explainability framework. It is using the SHAP library on its own, which is what Shapash does underneath for the model families it supports. The difference in approach is where the work sits. With SHAP directly, you write the plotting code, you decide how to present local versus global views, and you own the artifact that carries the explanation to a stakeholder, which in practice is a notebook, a slide or a static image. With Shapash, that presentation layer is the library's responsibility, and the trade is that you accept its choices about layout, filtering and what a sample's identity card contains.

That trade is worth taking when the explanation is a recurring deliverable rather than a one-off. It is not worth taking when you need a specific chart that Shapash does not produce, because you will end up writing the SHAP code anyway and maintaining both paths. The decision rule is simple: if you would otherwise build a dashboard around your explainer output, Shapash is that dashboard already built. If you would otherwise paste one plot into a report, it is overhead.

Maintenance, versioning and the Apache-2.0 terms

The release cadence visible in the supplied material shows three releases in 2026: v2.8.0 in January, v2.8.1 at the end of January, and v2.9.0 in May. The repository is not archived and the last push is dated 2026-09-10. A minor release roughly every few months with a patch in between is a normal maintenance rhythm for a library of this scope, and it means you should expect to move versions rather than pin once and forget.

The upgrade cost concentrates in two places. The 2.0.x refactor of compile and init attributes is the precedent: when the explainer's constructor changes, every script that builds an explainer changes with it. And because Shapash delegates to SHAP and LIME, a backend upgrade can change your numbers even when the Shapash version is unchanged. Pin both.

On licensing, Shapash is Apache-2.0, which is a permissive licence that permits commercial use and modification and includes an explicit patent grant. It also requires that you preserve notices and state significant changes. That is a summary of the licence's general character, not legal advice; if you are embedding Shapash in a distributed product, have your own counsel read the text. One thing the licence does not resolve is the licence of the backend you select, so check that separately if it differs from Shapash's.

Editorial conclusion

Adopt Shapash when the person who needs to understand the model is not the person who trained it, and when the deliverable is a browsable app rather than a notebook cell. Skip it if you need explainer values inside an automated pipeline, if your model is outside the supported list and you cannot supply a custom backend, or if you need exact per-prediction attribution as a contractual guarantee. Before committing, verify three things against your own stack: that your model type is in the supported list, that your dataset fits the memory profile of the web app you intend to launch, and that the Shapash version you pin still matches the SHAP version your environment already has, since Shapash is a wrapper and inherits its backend's breaking changes.

Official sources

1. License: Apache-2.0
2. MAIF/shapash on GitHub
3. Project website
4. README
5. Releases