pola-rs/polars · error · ModuleNotFoundError

'numpy' is required to convert numpy dtype

Error message

'numpy' is required to convert numpy dtype {dtype!r}

What it means

numpy_type_to_constructor maps a numpy array to a Series constructor; if numpy itself is not installed, the isinstance checks raise NameError, which is converted to ModuleNotFoundError. Polars treats numpy as an optional dependency for numpy-input conversion paths.

Solutions

1. Install numpy: pip install numpy (or pip install 'polars[numpy]').
2. Fix a shadowing module named numpy.py in the project that breaks the import.
3. Convert the input to plain Python lists before passing to polars.

Example fix

// before
pl.Series(np_like_array)  # numpy missing
// after
# pip install numpy
pl.Series(np.asarray(data))

import importlib.util
assert importlib.util.find_spec("numpy") is not None, "numpy is required for numpy-array input"

try:
    s = pl.Series(values)
except ModuleNotFoundError as e:
    if "'numpy' is required" in str(e):
        s = pl.Series(list(values))  # fallback to python list
    else:
        raise

When it happens

Trigger: Passing a numpy array (or object whose dtype attribute lookup touches the numpy module) to pl.Series/from_numpy in an environment where numpy is not installed. Rare, since arrays usually cannot exist without numpy, but can occur with duck-typed array wrappers.

Common situations: Minimal deployments where polars was installed without the numpy extra but some shim object mimics an ndarray; broken/partial numpy installs shadowed by a local numpy.py file.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• arr.dot query vector must be one-dimensional
• cannot convert DataFrame to
• cannot convert List column
• cannot parse numpy data type
• copy not allowed: cast from

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/3d6d0c103a248ec9. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/datatypes/constructor.py:157

) -> Callable[..., PySeries]:
    """Get the right PySeries constructor for the given Polars dtype."""
    if _NUMPY_TYPE_TO_CONSTRUCTOR is None:
        _set_numpy_to_constructor()
    try:
        return _NUMPY_TYPE_TO_CONSTRUCTOR[dtype]  # type:ignore[index]
    except KeyError:
        if len(values) > 0:
            first_non_nan = next(
                (v for v in values if isinstance(v, np.ndarray) or v == v), None
            )
            if isinstance(first_non_nan, str):
                return PySeries.new_str
            if isinstance(first_non_nan, bytes):
                return PySeries.new_binary
        return PySeries.new_object
    except NameError:  # pragma: no cover
        msg = f"'numpy' is required to convert numpy dtype {dtype!r}"
        raise ModuleNotFoundError(msg) from None


def py_type_to_constructor(py_type: type[Any]) -> Callable[..., PySeries]:
    """Get the right PySeries constructor for the given Python dtype."""
    py_type = (
        next((tp for tp in _PY_TYPE_TO_CONSTRUCTOR if issubclass(py_type, tp)), py_type)
        if py_type not in _PY_TYPE_TO_CONSTRUCTOR
        else py_type
    )
    return _PY_TYPE_TO_CONSTRUCTOR.get(py_type, PySeries.new_object)

View on GitHub (pinned to fe841f959e)