pytorch-grad-cam: Pixel Attribution for PyTorch Vision Models

What pytorch-grad-cam is actually for

The package addresses one narrow problem: given a trained PyTorch vision model and an input, produce a spatial map showing which pixels drove the output. The README frames the use case as diagnosing model predictions, either in production or while developing models, and states a second aim of serving as a benchmark of algorithms and metrics for research into new explainability methods. Those are two different audiences. The first is an engineer who has a model misbehaving on a slice of inputs and wants to see where it is looking. The second is a researcher comparing attribution techniques under a common interface. The project is not a training library, not a model zoo, and not a deployment tool. It attaches to a model you already have. Everything it does happens after the forward pass, through hooks and gradients, which is why it works across classification, object detection, semantic segmentation, embedding similarity and CLIP without any per-task model surgery.

Method selection is the real design decision

The README lists around twenty methods in a table, and the differences between them are not cosmetic. GradCAM weights 2D activations by the average gradient. GradCAM++ uses second order gradients. XGradCAM scales gradients by normalized activations. LayerCAM weights activations by positive gradients and the README notes it works better especially in lower layers. AblationCAM and ScoreCAM take a different route entirely: they perturb activations or the image and measure how the output drops, which means no gradient dependence at all. EigenCAM takes the first principal component of the activations and, per the README, offers no class discrimination. FEM is described as gradient free, binarizing activations with an activation > mean + k * std rule. HiResCAM is the one method in the table with an explicit guarantee: the README says it is provably guaranteed faithful for certain models, a qualifier worth reading literally rather than as a blanket claim. Two entries are meta-methods rather than alternatives. RefineCAM computes a CAM at multiple layers and combines them for higher resolution, and SESS runs CAMs over sliding window patches at multiple scales and fuses them. Both are documented as usable with any of the other CAM methods. That composability is the most interesting structural choice in the package, and it also means the configuration space is large enough that a default choice is not obvious.

Getting a first map running

Installation is a single command from the README: pip install grad-cam. The package name differs from the repository name, which is a common source of confusion when searching for it. The documented usage pattern is to construct a method object with your model and a list of target layers, then call it on a tensor. The target layer argument is the part that requires knowledge of your own architecture: you have to know which module in your network holds the spatial activations you want to attribute, and you have to pass that module object rather than a string name. The documentation site at jacobgil.github.io/pytorch-gradcam-book carries the advanced tutorials, including the per-task examples for detection, segmentation, embeddings and CLIP. The README also states that the package includes smoothing methods to make the CAMs look nice, and metrics for checking whether the explanations can be trusted. Those two features belong together. Smoothing changes the visual output, and the metrics are the only documented way to check whether the change helped or just made the map prettier.

Batching, memory and the cost of the perturbation methods

The README claims full support for batches of images in all methods. That claim matters more for some methods than others. Gradient-based approaches such as GradCAM, GradCAM++, XGradCAM and LayerCAM need one backward pass per batch, so cost scales roughly with batch size and is dominated by the backward pass itself. AblationCAM and ScoreCAM are structurally different: they modify activations or perturb the image and re-run the forward pass to measure the output drop. The README explicitly notes that the repository includes a fast batched implementation of AblationCAM, which reads as an acknowledgment that the naive version is slow. Even batched, the number of forward passes is tied to the number of channels or perturbation steps, so these methods are the ones to avoid when you need explanations for a large evaluation set. ShapleyCAM, which the README describes as weighting activations using the gradient and Hessian-vector product, sits in a third cost category because Hessian-vector products are more expensive than plain gradients. The practical consequence: if you plan to run attribution over thousands of images, the method you pick determines whether that job takes minutes or hours, and the README gives no timing numbers to help you guess.

Where this package is the wrong tool

The most direct limitation is architectural. Pixel attribution methods depend on spatial feature maps. If your model is a tabular network, a sequence model without spatial structure, or a vision model whose final layers have collapsed spatial dimensions before the point you can hook, there is nothing meaningful to attribute. The README's own method list assumes a 2D activation tensor throughout, and EigenCAM's description of taking the first principal component of the 2D activations makes that assumption explicit. A second limitation is interpretability of the output itself. A CAM is a heatmap, not an explanation in language, and the README offers no claim that a bright region corresponds to a causal factor in the input. The metrics it ships are described as a way to check whether you can trust the explanations, which implies the default answer is no until measured. A third issue is that the package supports many methods precisely because none of them is correct in all cases. If your workflow needs one stable, reproducible explanation per input for an audit trail, a menu of twenty methods with different outputs is a liability rather than a feature. You would need to fix a method, fix a target layer, and document both, at which point the package is doing less for you than its method count suggests.

How it compares to Captum and SHAP

Captum, maintained by Meta, is the closest general-purpose alternative and takes a broader approach: it covers attribution for vision, text and tabular models, and includes gradient-based, perturbation-based and game-theoretic methods in one library. The difference in approach is scope versus depth. Captum gives you a unified API across modalities and a smaller set of well-known methods. pytorch-grad-cam concentrates on vision and ships a wider set of CAM variants, including recent and less common entries such as KPCA-CAM, FinerCAM, SegEigenCAM and the two meta-methods, plus task-specific handling for detection and segmentation. If your problem is a vision model and you want to try several CAM-family methods on the same checkpoint, grad-cam has more to try. If your problem spans modalities, or you want a library with a formal specification of each method's guarantees, Captum is the more conservative choice. SHAP occupies different ground again: it is model-agnostic and built on Shapley values, so it can explain models that have no spatial activations at all, at a computational cost that scales with the number of features. The presence of ShapleyCAM in this package is worth noting as a sign that the Shapley framing has been adapted to the CAM setting, but that is a different algorithm from SHAP's model-agnostic estimator.

Maintenance, upgrades and the MIT licence

The repository is not archived and its last push date is recent, so it is receiving changes. The README carries a Tests workflow badge, which indicates a CI suite exists, but the README does not describe what that suite covers or which models it exercises. No releases were retrieved for this review, so there is no changelog to consult before upgrading, and the practical upgrade path is pinning a version and re-running your own attribution comparisons after a bump. That matters because a change in how gradients are accumulated or how a target layer is resolved would alter your maps without altering your model. The package is MIT licensed, which is permissive and imposes few conditions on redistribution, but the licence text itself is the authority and this is not legal advice. One licensing detail worth checking in your own context: the documentation site and the example images are separate artifacts from the pip package, and the MIT badge in the README refers to the repository.

What to verify before you build on it

Run one image through your own checkpoint with GradCAM and one perturbation method, and compare the maps. If they disagree substantially on the same input, that disagreement is the finding, and it tells you the explanation is method-dependent before you have shipped anything to a stakeholder. Check the spatial resolution of the map against the size of the objects you care about. A map computed from a late, low-resolution layer will not localize small defects, and the README's note that LayerCAM works better in lower layers is a hint that layer choice interacts with method choice. Then read the metrics section of the documentation and apply it to a held-out slice, because the package ships those metrics for exactly this purpose. The package is a reasonable dependency for a vision team that wants attribution diagnostics without writing hooks. It is a poor fit for anyone who needs a single guaranteed-faithful explanation across arbitrary architectures, and the README's own qualifier on HiResCAM, that its guarantee holds for certain models, is the honest boundary of what the library promises.

Editorial conclusion

Adopt grad-cam if you already have a PyTorch model and want saliency maps for classification, detection, segmentation or embedding similarity without writing the backprop hooks yourself. Do not adopt it if you need a method with formal guarantees for arbitrary architectures, or if you want a single canonical explanation rather than a menu of them. Before committing, verify on your own checkpoint that the layer you pass as target_layers produces a map at the spatial resolution you need, and read the metrics section of the documentation to check whether the explanations hold up on your data.

Official sources

1. Issues
2. jacobgil/pytorch-grad-cam on GitHub
3. License: MIT
4. Project website
5. README