{"record":{"id":"3d6d0c103a248ec9","repo":"pola-rs/polars","slug":"numpy-is-required-to-convert-numpy-dtype-dtype","errorCode":null,"errorMessage":"'numpy' is required to convert numpy dtype {dtype!r}","messagePattern":"'numpy' is required to convert numpy dtype (.+?)","errorType":"exception","errorClass":"ModuleNotFoundError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/datatypes/constructor.py","lineNumber":157,"sourceCode":") -> Callable[..., PySeries]:\n    \"\"\"Get the right PySeries constructor for the given Polars dtype.\"\"\"\n    if _NUMPY_TYPE_TO_CONSTRUCTOR is None:\n        _set_numpy_to_constructor()\n    try:\n        return _NUMPY_TYPE_TO_CONSTRUCTOR[dtype]  # type:ignore[index]\n    except KeyError:\n        if len(values) > 0:\n            first_non_nan = next(\n                (v for v in values if isinstance(v, np.ndarray) or v == v), None\n            )\n            if isinstance(first_non_nan, str):\n                return PySeries.new_str\n            if isinstance(first_non_nan, bytes):\n                return PySeries.new_binary\n        return PySeries.new_object\n    except NameError:  # pragma: no cover\n        msg = f\"'numpy' is required to convert numpy dtype {dtype!r}\"\n        raise ModuleNotFoundError(msg) from None\n\n\ndef py_type_to_constructor(py_type: type[Any]) -> Callable[..., PySeries]:\n    \"\"\"Get the right PySeries constructor for the given Python dtype.\"\"\"\n    py_type = (\n        next((tp for tp in _PY_TYPE_TO_CONSTRUCTOR if issubclass(py_type, tp)), py_type)\n        if py_type not in _PY_TYPE_TO_CONSTRUCTOR\n        else py_type\n    )\n    return _PY_TYPE_TO_CONSTRUCTOR.get(py_type, PySeries.new_object)\n","sourceCodeStart":139,"sourceCodeEnd":168,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/datatypes/constructor.py#L139-L168","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install numpy: pip install numpy (or pip install 'polars[numpy]').","Fix a shadowing module named numpy.py in the project that breaks the import.","Convert the input to plain Python lists before passing to polars."],"exampleFix":"// before\npl.Series(np_like_array)  # numpy missing\n// after\n# pip install numpy\npl.Series(np.asarray(data))","handlingStrategy":"try-catch","validationCode":"import importlib.util\nassert importlib.util.find_spec(\"numpy\") is not None, \"numpy is required for numpy-array input\"","typeGuard":null,"tryCatchPattern":"try:\n    s = pl.Series(values)\nexcept ModuleNotFoundError as e:\n    if \"'numpy' is required\" in str(e):\n        s = pl.Series(list(values))  # fallback to python list\n    else:\n        raise","preventionTips":["Install numpy in environments that feed arrays to polars (polars[numpy] extra)","Check for files shadowing the numpy module name","Add numpy to requirements when numpy-native paths are exercised"],"tags":["python","numpy","polars","dependency"],"backgroundTag":"missing-dependency","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}