Ohā¦ Seems completely removedā¦
find_pruneable_heads_and_indices is not just in a different place in Transformers 5.3.0.dev0. The evidence points to it being removed from the current v5 public internals, not relocated to another documented import path. In legacy v3 docs it lived under transformers.modeling_utils. In later v4 docs it lived under transformers.pytorch_utils. In current v5.3.0 docs, prune_linear_layer is still documented, but find_pruneable_heads_and_indices is no longer listed. The v4.57.1 source contains the function, while the v5.0.0 and current main pytorch_utils.py do not. (Hugging Face)
What changed
There is a clear timeline:
- v3.x: import from
transformers.modeling_utils was valid. (Hugging Face)
- v4.x: the helper was documented and implemented under
transformers.pytorch_utils. (Hugging Face)
- v5.x: the helper is absent from both the current docs and the current
pytorch_utils.py source, even though nearby helpers such as apply_chunking_to_forward and prune_linear_layer remain. (Hugging Face)
That is why your import fails. The library still has pruning-related helpers, but this specific helper is gone. (Hugging Face)
Why this is happening
Transformers v5 is a major cleanup release. The migration guide explicitly warns that a lot of paths were removed or reworked, and that custom code or remote code can break because old internal import paths no longer exist. That warning is broader than your one symbol, but it matches your situation exactly: code imported a low-level internal helper, then v5 changed the internals. (GitHub)
This is also not an isolated one-off. There are recent downstream reports of the exact same find_pruneable_heads_and_indices import error on Transformers 5.2.0, and other projects have hit similar breakages with adjacent helpers such as apply_chunking_to_forward after upgrading Transformers. (GitHub)
The practical answer
Best answer for your own code
Do not keep searching for a new official import path. I could not verify one in the current docs or source. The cleanest fix is to define the helper locally and import it from your own module instead. (Hugging Face)
Use this compatibility helper:
import torch
def find_pruneable_heads_and_indices(
heads: list[int],
n_heads: int,
head_size: int,
already_pruned_heads: set[int],
) -> tuple[set[int], torch.LongTensor]:
"""
Finds the heads and the flattened indices to keep, taking already-pruned heads
into account.
Parameters
----------
heads : list[int]
Head indices requested for pruning.
n_heads : int
Total number of attention heads before this pruning step.
head_size : int
Size of each attention head.
already_pruned_heads : set[int]
Heads that were pruned in earlier steps.
Returns
-------
tuple[set[int], torch.LongTensor]
(new_heads_to_prune, flattened_indices_to_keep)
"""
mask = torch.ones(n_heads, head_size, dtype=torch.bool)
heads = set(heads) - already_pruned_heads
for head in heads:
# Shift the head index left by however many smaller heads
# were already removed earlier.
shifted_head = head - sum(1 for h in already_pruned_heads if h < head)
mask[shifted_head] = False
index = torch.arange(n_heads * head_size)[mask.view(-1)].long()
return heads, index
This matches the old library behavior documented in legacy versions and shown in the v4 source. (Hugging Face)
Then replace:
from transformers.pytorch_utils import find_pruneable_heads_and_indices
with:
from my_compat import find_pruneable_heads_and_indices
If the failing import is inside a third-party package
Then the package is assuming an older Transformers internal API.
Use one of these two fixes:
Option A. Patch the package
Add a fallback import:
try:
from transformers.pytorch_utils import find_pruneable_heads_and_indices
except ImportError:
from .my_compat import find_pruneable_heads_and_indices
Option B. Pin Transformers to v4
If you do not want to patch the package, pin to a v4 release where the helper still exists.
pip install "transformers<5"
or a specific known-good release such as:
pip install "transformers==4.57.1"
That version still contains the function in transformers.pytorch_utils. (GitHub)
If your real goal is āprune attention headsā
If you only need head-pruning behavior, importing this helper directly is usually the fragile path. The older docs show it was mainly an internal utility used by model implementations to support prune_heads logic. If your model class already exposes a supported pruning method, use that instead of importing the helper. In older model code, the helper is used under the hood inside model attention modules rather than being the main user-facing API. (Hugging Face)
Why ājust downgradeā is not the only answer
You were right to suspect there should be a better way than blindly downgrading.
There are really three levels of fix:
-
Local shim
Best when this is your code. Small. Stable. Future-proof.
-
Patch the downstream package
Best when the error comes from external code you can edit.
-
Pin to v4
Best when you need the old behavior unchanged and want the least effort.
What is not a good use of time is hunting for a hidden v5 import path. The current docs and source do not support the idea that the function merely moved. (Hugging Face)
One subtle background detail
A real-world compatibility commit from September 2025 shows another repo updating imports so this helper came from transformers.pytorch_utils instead of older locations, specifically to restore compatibility with newer v4-era Transformers. That fits the historical pattern:
- old code imported from
modeling_utils
- later code imported from
pytorch_utils
- now in v5, the helper is gone entirely
So your failure is the next step in that evolution. (Hugging Face)
Bottom line
Your import fails because find_pruneable_heads_and_indices appears to have been removed in Transformers v5, not moved to a new documented module. The best fix is to vendor the old helper locally or pin to Transformers v4 if you need compatibility without patching. (GitHub)