huggingface/transformers · error · ImportError

Missing requirements in your local environment for `{path_or

Error message

Missing requirements in your local environment for `{path_or_repo_id}`:
{newline-joined failed}

What it means

For models with a requirements.txt in the repo, check_python_requirements parses each requirement, compares it against the installed version (handling specifiers like >=X.Y), and collects failures. If any requirement is unmet the ImportError lists each one with the installed version, e.g. 'transformers>=4.40.0 (installed: 4.36.2)'.

Source

Thrown at src/transformers/dynamic_module_utils.py:848

            except importlib.metadata.PackageNotFoundError:
                failed.append(f"{requirement} (installed: None)")
                continue

            if delimiter is not None and version_number is not None:
                is_satisfied = VersionComparison.from_string(delimiter).value(
                    version.parse(local_package_version), version.parse(version_number)
                )
            else:
                is_satisfied = True

            if not is_satisfied:
                failed.append(f"{requirement} (installed: {local_package_version})")

    except OSError:  # no requirements.txt
        pass

    if failed:
        raise ImportError(
            f"Missing requirements in your local environment for `{path_or_repo_id}`:\n" + "\n".join(failed)
        )

View on GitHub (pinned to a597f97485)

Solutions

1. pip install the listed packages at the listed minimum versions from the message.
2. Upgrade the environment (often upgrading transformers itself resolves it, since many repos pin transformers>=...).
3. If the comparison failed due to a weird local version, install a clean release of that package.

Example fix

# before: ImportError 'transformers>=4.40.0 (installed: 4.36.2)'
pip install transformers==4.36.2

# after
pip install -U 'transformers>=4.40.0'

from importlib.metadata import version, PackageNotFoundError
from packaging.requirements import Requirement

def check_requirements(reqs: list[str]) -> list[str]:
    failed = []
    for r in reqs:
        req = Requirement(r)
        try:
            v = version(req.name)
        except PackageNotFoundError:
            failed.append(r)
            continue
        if req.specifier and not req.specifier.contains(v, prereleases=True):
            failed.append(f"{r} (installed: {v})")
    return failed

try:
    AutoModel.from_pretrained(repo_id, trust_remote_code=True)
except ImportError as e:
    if "Missing requirements" in str(e):
        raise SystemExit(f"Upgrade environment per: {e}")
    raise

When it happens

Trigger: Loading a remote-code model whose repo ships requirements.txt where at least one line is unsatisfied — wrong installed version, missing package, or an unparsable local version string compared against a pinned specifier.

Common situations: Old transformers/torch versions in locked-down environments; new model repos tightening version pins after release; local installs with dev/non-standard version metadata that fail version.parse comparisons.

Related errors

• This modeling file requires the following packages that were
• return_tensors set to 'pt' but PyTorch can't be imported
• To use {type(self).__name__}, please install the following d
• {type(self).__name__} requires newer versions of: {', '.join
• You need to install optimum-quanto in order to use KV cache

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