pandas-dev/pandas · critical · ImportError

Please upgrade numpy to >= {_min_numpy_ver} to use this pand

Error message

Please upgrade numpy to >= {_min_numpy_ver} to use this pandas version.
Your numpy version is {_np_version}.

What it means

Raised at import time of pandas itself (compat/numpy/__init__.py:21-25) when the installed numpy is older than _min_numpy_ver ('1.26.0' at line 18). Because this module is imported during pandas startup, the ImportError surfaces as soon as you `import pandas`, before any pandas API is usable. The check uses Version(np.__version__) < Version('1.26.0').

Source

Thrown at pandas/compat/numpy/__init__.py:22

import numpy as np

from pandas.util.version import Version

# numpy versioning
_np_version = np.__version__
_nlv = Version(_np_version)
np_version_gt2 = _nlv >= Version("2.0.0")
np_version_gt2_2 = _nlv >= Version("2.2.0")
np_version_gt2_3 = _nlv >= Version("2.3.0")
np_version_gt2_5 = _nlv >= Version("2.5.0")
np_version_gt2_6 = _nlv >= Version("2.6.0.dev0")
is_numpy_dev = _nlv.dev is not None
_min_numpy_ver = "1.26.0"


if _nlv < Version(_min_numpy_ver):
    raise ImportError(
        f"Please upgrade numpy to >= {_min_numpy_ver} to use this pandas version.\n"
        f"Your numpy version is {_np_version}."
    )


np_long: type
np_ulong: type

if np_version_gt2:
    try:
        with warnings.catch_warnings():
            warnings.filterwarnings(
                "ignore",
                r".*In the future `np\.long` will be defined as.*",
                FutureWarning,
            )
            np_long = np.long
            np_ulong = np.ulong

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Upgrade numpy: pip install --upgrade 'numpy>=1.26.0'.
2. Verify with: python -c 'import numpy; print(numpy.__version__)' and ensure >= 1.26.0.
3. If you cannot upgrade numpy, install a pandas release compatible with your numpy (older pandas releases had lower numpy floors).
4. Recreate the venv/conda env cleanly so numpy and pandas resolve together.

Example fix

# before — ImportError on `import pandas` due to numpy 1.24
import pandas  # fails

# after
# shell: pip install --upgrade 'numpy>=1.26.0'
import pandas  # ok

import numpy as np
from packaging.version import Version
if Version(np.__version__) < Version('1.26.0'):
    raise SystemExit(f'numpy>=1.26.0 required, got {np.__version__}')

try:
    import pandas
except ImportError as e:
    if 'Please upgrade numpy' in str(e):
        # instruct user/environment to upgrade numpy
        ...
    raise

When it happens

Trigger: `import pandas` in an environment whose numpy is < 1.26.0. This is a hard floor: even numpy 1.25.x fails. Common after installing a newer pandas into an env that still has an older numpy, or on a system Python with an ancient numpy.

Common situations: Upgrading pandas via pip without --upgrade numpy; conda env mixing channels; a Docker base image with old numpy; a CI matrix that didn't bump numpy alongside pandas.

Related errors

• Can't determine version for {module.__name__}
• `Import {install_name}` failed. {extra} Use pip, conda, or y
• Pandas requires version '{minimum_version}' or newer of '{pa
• Unable to import required dependency {_dependency}. Please s
• C extension: {_module} not built. If you want to import pand

AI-assisted analysis of pandas-dev/pandas@71959b8cb9 (2026-08-07). Data as JSON: /api/errors/9492f898b3f48768. Report an issue: GitHub.