huggingface/transformers · error · ImportError

Missing requirements in your local environment for

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)'.

Solutions

pip install the listed packages at the listed minimum versions from the message.
Upgrade the environment (often upgrading transformers itself resolves it, since many repos pin transformers>=...).
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'

Defensive patterns

Strategy: try-catch

Validate before calling

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 / catch

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

Prevention

Read the repo's requirements.txt before loading remote models.
Keep core deps (transformers, torch) current.
Verify environment parity between writer and loader machines.

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

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

Appendix: 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)