huggingface/transformers · error · ImportError

To use {type(self).name}, please install the following d

Error message

To use {type(self).__name__}, please install the following dependencies: {specs}

What it means

HfExporter's dependency guard raises ImportError when any package listed in the exporter's required_packages is not installed. The message names the exporter class (e.g. OnnxExporter, ExecutorchExporter) and the exact pip spec, pinning the tested version when one is recorded in tested_versions (e.g. onnx==1.21.0).

Source

Thrown at src/transformers/exporters/base.py:82

        # target the public API, not the build.
        missing, drift = [], []
        for pkg in self.required_packages:
            exists, installed = _is_package_available(pkg, return_version=True)
            if not exists:
                missing.append(pkg)
                continue
            tested = self.tested_versions.get(pkg)
            if tested is not None and installed != "N/A":
                installed_base = installed.split("+", 1)[0]
                tested_base = tested.split("+", 1)[0]
                if installed_base != tested_base:
                    drift.append((pkg, installed_base, tested_base))

        if missing:
            specs = ", ".join(
                f"{pkg}=={self.tested_versions[pkg]}" if pkg in self.tested_versions else pkg for pkg in missing
            )
            raise ImportError(f"To use {type(self).__name__}, please install the following dependencies: {specs}")

        # Enforce hard minimums; collect all violations and report once, rather than failing on the first.
        outdated = []
        for pkg, minimum in self.min_versions.items():
            _, installed = _is_package_available(pkg, return_version=True)
            if installed == "N/A" or version.parse(installed.split("+", 1)[0]) < version.parse(minimum):
                outdated.append(f"{pkg}>={minimum} (found {installed})")
        if outdated:
            raise ImportError(f"{type(self).__name__} requires newer versions of: {', '.join(outdated)}")

        if drift:
            details = ", ".join(f"{pkg}: installed {got}, tested {want}" for pkg, got, want in drift)
            logger.warning(
                f"{type(self).__name__} is experimental and patches many backend internals; "
                f"behaviour may differ from what was validated. Version drift detected — {details}. "
                f"If you hit issues, try the tested versions."
            )

View on GitHub (pinned to a597f97485)

Solutions

Install exactly what the message specifies: pip install "onnx==1.21.0" "onnxscript==0.7.0" (or pip install executorch==1.3.1 for ExecuTorch).
Or install without pins if you accept drift: pip install onnx onnxscript.
Pre-check availability in your code with transformers.utils.is_package_available / importlib.util.find_spec before constructing the exporter.

Example fix

# before
OnnxExporter().export(model, inputs, OnnxConfig())  # ImportError: onnx, onnxscript

# after (shell)
# pip install onnx==1.21.0 onnxscript==0.7.0
OnnxExporter().export(model, inputs, OnnxConfig())

Defensive patterns

Strategy: validation

Validate before calling

from importlib.util import find_spec

REQUIRED = {"onnx": "onnx==1.21.0", "onnxscript": "onnxscript==0.7.0"}  # read from exporter.required_packages
deps = {pkg: spec for pkg, spec in REQUIRED.items() if find_spec(pkg) is None}
if deps:
    raise SystemExit("pip install " + " ".join(deps.values()))

Try / catch

try:
    exporter.export(model, inputs, cfg)
except ImportError as e:
    if "please install" in str(e):
        subprocess.check_call([sys.executable, "-m", "pip", "install", *parse_specs(e)])  # or surface to user
    else:
        raise

Prevention

Declare export extras in your project's requirements (onnx, onnxscript, executorch) up front
In containers, install optional deps in the image rather than at runtime
Check exporter.required_packages / .tested_versions programmatically before exporting

When it happens

Trigger: Calling OnnxExporter.export without onnx/onnxscript installed, or ExecutorchExporter.export without executorch — the check runs as part of the exporter's dependency validation before any tracing work.

Common situations: Fresh environment or slim transformers install missing optional export extras; CI image built for training only; installing transformers[onnx]-style extras was skipped.

Related errors

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