{"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/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/datatypes/constructor.py#L139-L168","documentation":"Raised when polars must map a numpy dtype to a Series constructor but numpy is not installed in the environment. The lookup helper references the 'np' namespace inside a try block, and the resulting NameError is converted into ModuleNotFoundError. It signals a missing optional dependency, not a problem with your data.","triggerScenarios":"Calling pl.Series(...) or related constructor helpers with a numpy dtype object (or values that require numpy dtype resolution) in an environment where 'import numpy' fails, hitting the except NameError branch in numpy_type_to_constructor.","commonSituations":"Slim Docker images or CI runners where numpy was pruned to save space; a venv rebuilt without numpy after polars was installed; partial/failed numpy installs; relying on polars' optional numpy extra that is not present.","solutions":["Install numpy: pip install numpy (or pip install 'polars[numpy]')","If numpy cannot be installed, pass pure-Python containers (list/tuple) with an explicit polars dtype so the numpy constructor lookup is never reached"],"exampleFix":"# before (environment without numpy)\npl.Series(np_dtype_object_values)  # ModuleNotFoundError\n\n# after\n# pip install numpy\n# or: pass plain Python data\npl.Series([1, 2, 3], dtype=pl.Int64)","handlingStrategy":"validation","validationCode":"import importlib.util\n\nif importlib.util.find_spec('numpy') is None:\n    raise SystemExit('numpy is required for numpy-dtyped inputs: pip install numpy')\n\nimport numpy as np  # safe now\ns = pl.Series(values)","typeGuard":null,"tryCatchPattern":"try:\n    s = pl.Series(values)\nexcept ModuleNotFoundError as e:\n    if \"'numpy' is required\" in str(e):\n        raise RuntimeError('install numpy: pip install numpy') from e\n    raise","preventionTips":["Declare 'polars[numpy]' in requirements when numpy-dtyped data is in scope","Probe numpy availability at app startup, not mid-computation"],"tags":["numpy","environment","dependency","import","module-not-found"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}