pandas-dev/pandas · error · ImportError

`Import ` failed. Use pip, conda, or your preferred package…

Error message

`Import {install_name}` failed. {extra} Use pip, conda, or your preferred package management tool to install the {install_name} package.

What it means

Raised by `import_optional_dependency` when an optional dependency module cannot be imported and `errors='raise'` (the default). pandas wraps the underlying ImportError with a friendly install hint naming the pip/conda package. The `{install_name}` reflects INSTALL_MAPPING (e.g. 'lxml.etree' -> 'lxml', 'tables' -> 'pytables').

Solutions

1. Install the named package: `pip install <install_name>` or `conda install <install_name>`.
2. Install pandas with the relevant extra: `pip install 'pandas[performance]'` or `'pandas[html]'`.
3. Pass `errors='warn'` or `errors='ignore'` if your code path is optional and should degrade gracefully.

Example fix

// before
pd.read_html('https://example.com/table')  # lxml not installed

// after
pip install lxml
pd.read_html('https://example.com/table')

import importlib.util
is_installed = importlib.util.find_spec(name) is not None

try:
    from pandas.compat._optional import import_optional_dependency
    mod = import_optional_dependency(name, errors='warn')
except ImportError:
    mod = None  # degrade gracefully

When it happens

Trigger: Calling `pd.read_html(url)` without lxml/bs4 installed; `pd.read_excel` without openpyxl; `to_sql` without SQLAlchemy; any code path that internally invokes `import_optional_dependency(name, errors='raise')` for a missing package.

Common situations: Fresh environment without optional extras; CI images trimmed to minimal deps; users who installed only `pandas` and not `pandas[all]`.

Related errors

• Can't determine version for
• Pandas requires version
• Please upgrade numpy to >=

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

Appendix: source

Thrown at pandas/compat/_optional.py:162

        None is returned when the package is not found and `errors`
        is False, or when the package's version is too old and `errors`
        is ``'warn'`` or ``'ignore'``.
    """
    assert errors in {"warn", "raise", "ignore"}

    package_name = INSTALL_MAPPING.get(name)
    install_name = package_name if package_name is not None else name

    msg = (
        f"`Import {install_name}` failed. {extra} "
        f"Use pip, conda, or your preferred package management tool "
        f"to install the {install_name} package."
    )
    try:
        module = importlib.import_module(name)
    except ImportError as err:
        if errors == "raise":
            raise ImportError(msg) from err
        return None

    # Handle submodules: if we have submodule, grab parent module from sys.modules
    parent = name.split(".", maxsplit=1)[0]
    if parent != name:
        install_name = parent
        module_to_get = sys.modules[install_name]
    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":

View on GitHub (pinned to 3b7651241d)