huggingface/transformers · error · RuntimeError

PyTorch must be installed to return a PyTorch dataset.

Error message

PyTorch must be installed to return a PyTorch dataset.

What it means

Raised by squad_convert_examples_to_features when return_dataset='pt' but PyTorch is not installed. The function then proceeds to build torch.tensor objects and a TensorDataset, so it checks availability first and fails fast with a RuntimeError rather than an opaque NameError on the missing torch import.

Source

Thrown at src/transformers/data/processors/squad.py:399

    new_features = []
    unique_id = 1000000000
    example_index = 0
    for example_features in tqdm(
        features, total=len(features), desc="add example index and unique id", disable=not tqdm_enabled
    ):
        if not example_features:
            continue
        for example_feature in example_features:
            example_feature.example_index = example_index
            example_feature.unique_id = unique_id
            new_features.append(example_feature)
            unique_id += 1
        example_index += 1
    features = new_features
    del new_features
    if return_dataset == "pt":
        if not is_torch_available():
            raise RuntimeError("PyTorch must be installed to return a PyTorch dataset.")

        # Convert to Tensors and build dataset
        all_input_ids = torch.tensor([f.input_ids for f in features], dtype=torch.long)
        all_attention_masks = torch.tensor([f.attention_mask for f in features], dtype=torch.long)
        all_token_type_ids = torch.tensor([f.token_type_ids for f in features], dtype=torch.long)
        all_cls_index = torch.tensor([f.cls_index for f in features], dtype=torch.long)
        all_p_mask = torch.tensor([f.p_mask for f in features], dtype=torch.float)
        all_is_impossible = torch.tensor([f.is_impossible for f in features], dtype=torch.float)

        if not is_training:
            all_feature_index = torch.arange(all_input_ids.size(0), dtype=torch.long)
            dataset = TensorDataset(
                all_input_ids, all_attention_masks, all_token_type_ids, all_feature_index, all_cls_index, all_p_mask
            )
        else:
            all_start_positions = torch.tensor([f.start_position for f in features], dtype=torch.long)
            all_end_positions = torch.tensor([f.end_position for f in features], dtype=torch.long)
            dataset = TensorDataset(

View on GitHub (pinned to a597f97485)

Solutions

1. pip install torch if you actually want the TensorDataset output.
2. If you are on TF/JAX, pass return_dataset='tf' or omit it and build the dataset with your framework from the returned features.
3. Gate on transformers.utils.is_torch_available() in shared scripts to choose the right return_dataset per environment.

Example fix

# before
features, dataset = squad_convert_examples_to_features(examples, tokenizer, 384, 128, return_dataset='pt')  # no torch installed

# after
features, dataset = squad_convert_examples_to_features(examples, tokenizer, 384, 128, return_dataset='tf')

from transformers.utils import is_torch_available

return_dataset = 'pt' if is_torch_available() else 'tf'
features, dataset = squad_convert_examples_to_features(
    examples, tokenizer, max_seq_length=384, doc_stride=128, return_dataset=return_dataset
)

def has_torch() -> bool:
    try:
        import torch  # noqa: F401
        return True
    except ImportError:
        return False

try:
    features, dataset = squad_convert_examples_to_features(examples, tok, 384, 128, return_dataset='pt')
except RuntimeError as e:
    if 'PyTorch must be installed' in str(e):
        features, _ = squad_convert_examples_to_features(examples, tok, 384, 128)  # features only
    else:
        raise

When it happens

Trigger: Calling squad_convert_examples_to_features(..., return_dataset='pt') in an environment where torch is absent — e.g. a TensorFlow/JAX-only install of transformers, or a slim deployment image.

Common situations: Reusing a SQuAD preprocessing script inside a TF-only training stack; CI environments that install transformers without torch; Docker images trimmed of PyTorch for inference.

Related errors

• No valid predictions
• SquadProcessor should be instantiated via SquadV1Processor o
• return_tensors set to 'pt' but PyTorch can't be imported
• Unable to convert output to PyTorch tensors format, PyTorch
• mode is not a valid split name

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/bccc2d26f8b58d2d. Report an issue: GitHub.