huggingface/transformers · error · RuntimeError

You picked the {self.name} backend, but it is not installed.

Error message

You picked the {self.name} backend, but it is not installed. Run {self.pip_install()}.

What it means

Error "You picked the {self.name} backend, but it is not installed. Run {self.pip_install()}." thrown in huggingface/transformers.

Source

Thrown at src/transformers/hyperparameter_search.py:51

class HyperParamSearchBackendBase:
    name: str
    pip_package: str | None = None

    @staticmethod
    def is_available():
        raise NotImplementedError

    def run(self, trainer, n_trials: int, direction: str, **kwargs):
        raise NotImplementedError

    def default_hp_space(self, trial):
        raise NotImplementedError

    def ensure_available(self):
        if not self.is_available():
            raise RuntimeError(
                f"You picked the {self.name} backend, but it is not installed. Run {self.pip_install()}."
            )

    @classmethod
    def pip_install(cls):
        return f"`pip install {cls.pip_package or cls.name}`"


class OptunaBackend(HyperParamSearchBackendBase):
    name = "optuna"

    @staticmethod
    def is_available():
        return is_optuna_available()

    def run(self, trainer, n_trials: int, direction: str, **kwargs):
        return run_hp_search_optuna(trainer, n_trials, direction, **kwargs)

View on GitHub (pinned to a597f97485)

Solutions

1. Install the selected backend with the suggested pip command.
2. Choose a different hyperparameter search backend that is installed.

When it happens

Trigger: Raised in hyperparameter_search when the chosen backend (optuna, ray, sigopt, wandb) is not installed.

Common situations: Calling Trainer.hyperparameter_search with a backend whose extra package is missing from the environment.

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