{"library":"shap","title":"SHAP (SHapley Additive exPlanations)","description":"SHAP is a Python library that provides a unified approach to explain the output of any machine learning model using Shapley values, a concept from game theory. It offers various 'explainers' optimized for different model types (e.g., tree models, deep learning models, or model-agnostic approaches) and powerful visualization tools. Currently at version 0.51.0, it maintains an active development cycle with minor releases typically occurring every month or two.","status":"active","version":"0.51.0","language":"en","source_language":"en","source_url":"http://github.com/shap/shap","tags":["machine learning","explainable AI","XAI","model interpretation","shapley values","ml explainability"],"install":[{"cmd":"pip install shap","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core dependency for numerical operations, required by most explainers.","package":"numpy","optional":false},{"reason":"Commonly used for data handling with tabular explainers and datasets.","package":"pandas","optional":true},{"reason":"For training various machine learning models that SHAP can explain.","package":"scikit-learn","optional":true},{"reason":"Highly optimized TreeExplainer is available for XGBoost models.","package":"xgboost","optional":true},{"reason":"Highly optimized TreeExplainer is available for LightGBM models.","package":"lightgbm","optional":true},{"reason":"Required for generating SHAP plots.","package":"matplotlib","optional":true}],"imports":[{"symbol":"shap","correct":"import shap"},{"note":"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.","wrong":"explainer = shap.TreeExplainer(model, data) # or other specific explainer for general use","symbol":"shap.Explainer","correct":"explainer = shap.Explainer(model, data)"},{"note":"The `explainer` object is now callable and returns a `shap.Explanation` object. The `.shap_values()` method is part of the old API.","wrong":"shap_values = explainer.shap_values(data)","symbol":"shap_values","correct":"shap_values = explainer(data)"},{"note":"`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.","wrong":"shap.summary_plot(shap_values, data)","symbol":"shap.plots.beeswarm","correct":"shap.plots.beeswarm(shap_values)"}],"quickstart":{"code":"import shap\nimport xgboost\nimport pandas as pd\nfrom sklearn.datasets import make_classification\n\n# Generate synthetic data\nX, y = make_classification(n_samples=1000, n_features=10, n_informative=5, n_redundant=2, n_classes=2, random_state=42)\nX = pd.DataFrame(X, columns=[f'feature_{i}' for i in range(X.shape[1])])\n\n# Train an XGBoost model\nmodel = xgboost.XGBClassifier(use_label_encoder=False, eval_metric='logloss', random_state=42)\nmodel.fit(X, y)\n\n# For Jupyter notebooks, uncomment the following line to enable JavaScript visualizations:\n# shap.initjs()\n\n# Create a SHAP Explainer (automatically infers TreeExplainer for XGBoost)\nexplainer = shap.Explainer(model, X)\n\n# Calculate SHAP values for the dataset\nshap_values = explainer(X)\n\n# Visualize the global impact of features using a beeswarm plot\n# This plot shows the distribution of SHAP values for each feature.\nshap.plots.beeswarm(shap_values, max_display=10)\n\n# To visualize an individual prediction (e.g., the first instance) with a waterfall plot:\n# shap.plots.waterfall(shap_values[0])","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.11 or a later compatible version.","message":"SHAP 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.","severity":"breaking","affected_versions":">=0.50.0"},{"fix":"Update 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.","message":"The 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.","severity":"breaking","affected_versions":">=0.36.0, especially >=0.46.0"},{"fix":"Carefully 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.","message":"While 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.","severity":"gotcha","affected_versions":">=0.46.0"},{"fix":"Prefer `shap.TreeExplainer` for tree-based models. For non-tree models, consider sampling your background data or using approximate explainers where appropriate for performance.","message":"For 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}