pandas-dev/pandas · error · ImportError

Pandas requires version

Error message

Pandas requires version '{minimum_version}' or newer of '{parent}' (version '{version}' currently installed).

What it means

Raised by `import_optional_dependency` when an optional dependency is importable but its version is older than the minimum pandas requires (from the VERSIONS table or an explicit `min_version` argument) and `errors='raise'`. The message shows the required floor, the parent package, and the detected version. With `errors='warn'` the same condition emits a UserWarning and returns None instead.

Solutions

Upgrade the named package: `pip install -U <parent>`.
Verify the installed version: `python -c 'import <parent>; print(<parent>.__version__)'`.
If you cannot upgrade, downgrade pandas to a release whose VERSIONS table accepts your dependency version.

Example fix

// before
pip install openpyxl==1.8  # too old

// after
pip install -U openpyxl

Defensive patterns

Strategy: validation

Validate before calling

from packaging.version import Version
import <parent>
assert Version(<parent>.__version__) >= Version(minimum)

Try / catch

try:
    import_optional_dependency(name, min_version='2.0')
except ImportError:
    # instruct user to upgrade; degrade
    pass

Prevention

Pin optional deps to >= the pandas VERSIONS table in your requirements.
Run `pip check` in CI to catch stale combinations.

When it happens

Trigger: `pd.read_excel` with openpyxl < the listed minimum; `to_sql` with an old SQLAlchemy; passing `min_version='2.0'` to `import_optional_dependency` with an older installed version.

Common situations: Long-lived conda environments with stale optional deps; Docker images pinned to old versions; partial upgrades where pandas was bumped but deps were not.

Related errors

AI-assisted analysis of pandas-dev/pandas@3b7651241d (2026-08-11). Data as JSON: /api/errors/f65f38a930cbeb71. Report an issue: GitHub.

Appendix: source

Thrown at pandas/compat/_optional.py:188

    else:
        module_to_get = module
    minimum_version = min_version if min_version is not None else VERSIONS.get(parent)
    if minimum_version:
        version = get_version(module_to_get)
        if version and Version(version) < Version(minimum_version):
            msg = (
                f"Pandas requires version '{minimum_version}' or newer of '{parent}' "
                f"(version '{version}' currently installed)."
            )
            if errors == "warn":
                warnings.warn(
                    msg,
                    UserWarning,
                    stacklevel=find_stack_level(),
                )
                return None
            elif errors == "raise":
                raise ImportError(msg)
            else:
                return None

    return module

View on GitHub (pinned to 3b7651241d)