pandas-dev/pandas · critical · ImportError

C extension: not built. If you want to import pandas from…

Error message

C extension: {_module} not built. If you want to import pandas from the source directory, you may need to run 'python -m pip install -ve . --no-build-isolation -Ceditable-verbose=true' to build the C extensions first.

What it means

Raised when importing `pandas.compat` (or its transitive C-extension submodule named in `_err.name`) fails with an ImportError during pandas init. This almost always means a compiled extension inside pandas itself was not built, which happens with an editable/source checkout that was never compiled. The message points at the exact build command pandas recommends.

Solutions

1. Run the exact command in the message: `python -m pip install -ve . --no-build-isolation -Ceditable-verbose=true` from the repo root.
2. Ensure build prerequisites are present: `pip install setuptools wheel Cython numpy` and a working C compiler.
3. Clean stale artifacts then rebuild: remove `build/` and any `*.so`/`*.pyd`, then reinstall.
4. If you did not intend an editable install, do a normal `pip install pandas` (or uninstall the editable version first).

Example fix

// before
cd pandas-source && pip install -e .
python -c "import pandas"
# ImportError: C extension: ... not built. ...

// after
python -m pip install -ve . --no-build-isolation -Ceditable-verbose=true
python -c "import pandas; print(pandas.__version__)"

import importlib.util, sys
def pandas_extensions_built() -> bool:
    # the import that triggers the C-extension load path
    try:
        import pandas.compat  # noqa: F401
        return True
    except ImportError:
        return False
# in dev setup scripts: build first, then assert this is True

null

try:
    import pandas
except ImportError as e:
    if 'C extension' in str(e) and 'not built' in str(e):
        # run the documented build command, then retry
        ...
    raise

When it happens

Trigger: Running `import pandas` from a source clone after `pip install -e .` (or just adding the dir to sys.path) without having compiled the Cython/C extensions; the `from pandas.compat import is_numpy_dev` line at pandas/__init__.py:22 triggers a deeper C-extension import that fails.

Common situations: Developer checkout without a build step; missing build toolchain (Cython, compiler, numpy headers) during install; stale build artifacts after a git pull that added new extensions; `--no-build-isolation` used incorrectly so build deps were absent.

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

Appendix: source

Thrown at pandas/__init__.py:27

for _dependency in _hard_dependencies:
    try:
        __import__(_dependency)
    except ImportError as _e:  # pragma: no cover
        raise ImportError(
            f"Unable to import required dependency {_dependency}. "
            "Please see the traceback for details."
        ) from _e

del _hard_dependencies, _dependency

try:
    # numpy compat
    from pandas.compat import (
        is_numpy_dev as _is_numpy_dev,  # pyright: ignore[reportUnusedImport] # noqa: F401
    )
except ImportError as _err:  # pragma: no cover
    _module = _err.name
    raise ImportError(
        f"C extension: {_module} not built. If you want to import "
        "pandas from the source directory, you may need to run "
        "'python -m pip install -ve . --no-build-isolation -Ceditable-verbose=true' "
        "to build the C extensions first."
    ) from _err

from pandas._config import (
    get_option,
    set_option,
    reset_option,
    describe_option,
    option_context,
    options,
)

# let init-time option registration happen
import pandas.core.config_init  # pyright: ignore[reportUnusedImport] # noqa: F401

View on GitHub (pinned to 3b7651241d)