numpy/numpy · critical · ImportError

Error importing numpy: you should not try to import numpy fr

Error message

Error importing numpy: you should not try to import numpy from
            its source directory; please exit the numpy source tree, and relaunch
            your python interpreter from there.

What it means

NumPy raises this ImportError when the build-generated module `numpy.__config__` cannot be found, which only happens when you run Python from inside the uninstalled NumPy source checkout. The `__config__.py` file is created at build/install time and is absent in a raw git clone. NumPy uses this as a signal that you are not running an installed copy.

Source

Thrown at numpy/__init__.py:116

    __NUMPY_SETUP__  # noqa: B018
except NameError:
    __NUMPY_SETUP__ = False

if __NUMPY_SETUP__:
    sys.stderr.write('Running from numpy source directory.\n')
else:
    # Allow distributors to run custom init code before importing numpy._core
    from . import _distributor_init

    try:
        from numpy.__config__ import show_config
    except ImportError as e:
        if isinstance(e, ModuleNotFoundError) and e.name == "numpy.__config__":
            # The __config__ module itself was not found, so add this info:
            msg = """Error importing numpy: you should not try to import numpy from
            its source directory; please exit the numpy source tree, and relaunch
            your python interpreter from there."""
            raise ImportError(msg) from e
        raise

    from . import _core
    from ._core import (
        False_,
        ScalarType,
        True_,
        abs,
        absolute,
        acos,
        acosh,
        add,
        all,
        allclose,
        amax,
        amin,
        any,
        arange,

View on GitHub (pinned to e117b3ca4e)

Solutions

Exit the numpy source directory (cd to your home or project dir) before launching Python, so it picks up the installed numpy.
Install numpy properly first: run `pip install .` (or `meson install`) from the source tree so __config__.py is generated.
If developing numpy, use an editable/dev install: `python -m pip install -e . --no-build-isolation` after installing build deps.
Verify with `python -c 'import numpy; print(numpy.__file__)'` from outside the source dir that the installed copy is used.

Example fix

// before (run from inside numpy source root)
$ cd numpy-repo/numpy
$ python -c 'import numpy'   # ImportError

// after
$ cd ~
$ python -c 'import numpy; print(numpy.__version__)'

Defensive patterns

Strategy: validation

Validate before calling

import os, sys
# detect running from numpy source tree before importing
here = os.path.abspath(os.getcwd())
if os.path.exists(os.path.join(here, 'numpy', '__init__.py')) and \
   not os.path.exists(os.path.join(here, 'numpy', '__config__.py')):
    raise SystemExit('Refusing to import numpy from its unbuilt source tree; cd out and use the installed copy.')

Try / catch

try:
    import numpy as np
except ImportError as e:
    if 'source directory' in str(e):
        raise SystemExit('Run from outside the numpy source tree; install numpy first.')
    raise

Prevention

Always install numpy (pip install numpy or pip install -e .) before importing it.
Run Python from a project dir outside any cloned numpy checkout.
In CI, separate the build step from the test step and import only after install.

When it happens

Trigger: Running `python -c 'import numpy'` or any script from within the numpy source tree directory before running `pip install .` or `meson install`. Also triggered when a packaging tool or editable install left the source dir without generating `__config__.py`.

Common situations: Cloning numpy from git and immediately trying to `import numpy` from the repo root; developers debugging numpy itself without setting `__NUMPY_SETUP__`; CI that checks out source but skips the build step.

Related errors

AI-assisted analysis of numpy/numpy@e117b3ca4e (2026-08-07). Data as JSON: /api/errors/317e877f2994fd1f. Report an issue: GitHub.