Install & Compatibility
Where this runs
tested against v0.0.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
py 3.13
✕ build_error
✓ 62.83s
2479MB installed
● package 2479MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
IntegratedGradients
✓ from captum.attr import IntegratedGradients
A primary feature attribution algorithm.
DeepLift
✓ from captum.attr import DeepLift
Another common attribution method.
LayerConductance
✓ from captum.attr import LayerConductance
For attributing to specific layers.
LLMAttribution
✓ from captum.attr import LLMAttribution
Introduced in v0.7.0 for language model attribution.
This quickstart demonstrates how to apply Integrated Gradients, a popular feature attribution method, to a simple PyTorch `ToyModel`. It covers defining the model, preparing inputs and baselines, instantiating an attribution algorithm, and computing feature attributions.
import torch
import torch.nn as nn
from captum.attr import IntegratedGradients
# 1. Define a simple PyTorch model
class ToyModel(nn.Module):
def __init__(self):
super().__init__()
self.lin1 = nn.Linear(3, 3)
self.relu = nn.ReLU()
self.lin2 = nn.Linear(3, 2)
def forward(self, input):
return self.lin2(self.relu(self.lin1(input)))
model = ToyModel()
model.eval() # Set model to evaluation mode
# 2. Define input and baseline tensors
input_tensor = torch.rand(2, 3, requires_grad=True)
baseline_tensor = torch.zeros(2, 3)
# 3. Instantiate an attribution algorithm (e.g., Integrated Gradients)
ig = IntegratedGradients(model)
# 4. Compute attributions
# target specifies the output index to explain (e.g., target=0 for the first output class)
attributions, delta = ig.attribute(input_tensor, baseline_tensor, target=0, return_convergence_delta=True)
print('Input Tensor:', input_tensor)
print('IG Attributions:', attributions)
print('Convergence Delta:', delta)
captum --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'captum'
The `captum` library is not installed in the current Python environment, or there's an issue with the environment's `PYTHONPATH`.
fixInstall the library using pip: `pip install captum` or if using conda, try `conda install captum -c conda-forge` as `conda install captum -c pytorch` has been reported to cause issues.
AssertionError: Target not provided when necessary, cannot take gradient with respect to multiple outputs.
Captum's attribution methods, especially gradient-based ones, require a specific scalar output to attribute to if the model produces multiple outputs. The `target` parameter was either omitted or incorrectly specified for a multi-dimensional output.
fixProvide a `target` argument to the attribution method, specifying the index of the output (or a tuple of indices for higher-dimensional outputs) for which attributions are desired. For a batch, a list/tensor of targets can be provided. If attributing to a sum of outputs, wrap the model's forward function to sum the desired outputs and pass this wrapper as `forward_func`.
AttributeError: module 'captum' has no attribute 'attr'
This typically occurs when attempting to access submodules like `attr` (which contains attribution algorithms) directly after a simple `import captum` statement, instead of importing the submodule explicitly.
fixExplicitly import the required submodules, for example, `from captum.attr import IntegratedGradients` or `import captum.attr as attr`.
RuntimeError: CUDA out of memory
Some Captum attribution methods, especially those with an `n_steps` argument like Integrated Gradients or perturbation-based methods with many perturbations, can be memory-intensive, leading to GPU out-of-memory errors.
fixReduce the `n_steps` parameter, use the `internal_batch_size` argument to process expanded inputs in smaller batches, or decrease `perturbations_per_eval` for perturbation-based methods.
TypeError: Module type <class 'torch.nn.modules.upsampling.Upsample'> is not supported.No default rule defined.
When using Layer-wise Relevance Propagation (LRP), this error indicates that a module type in the model (e.g., `torch.nn.Upsample` or `nn.ConvTranspose2d`) does not have a pre-defined propagation rule in Captum's LRP implementation.
fixDefine and explicitly register a custom propagation rule for the unsupported module type, inheriting from `captum.attr.LRP.PropagationRule`, or use a different attribution method that supports the model architecture.
Upgrade
Version history
0.9.0latest on PyPI · released Apr 17, 2026
Audit
Dependencies
torchrequiredCore deep learning framework dependency.
numpyrequiredNumerical operations, required by Captum methods. Version <2.0 is specified.
packagingrequiredDependency for package management utilities.
tqdmrequiredProgress bar for iterative processes.
matplotliboptionalUsed for visualization in tutorials and some internal plotting functionalities.