{"id":21743,"library":"pydantic-numpy","title":"Pydantic NumPy","description":"Integrate NumPy arrays into Pydantic models with type validation, shape constraints, and dtype checking. Currently version 9.0.1 (requires Python >=3.11, <3.15). Active development with frequent breaking changes across major versions.","status":"active","version":"9.0.1","language":"python","source_language":"en","source_url":"https://github.com/caniko/pydantic-numpy","tags":["pydantic","numpy","validation","data-science"],"install":[{"cmd":"pip install pydantic-numpy","lang":"bash","label":"Install"}],"dependencies":[{"reason":"Core dependency for array data types.","package":"numpy","optional":false},{"reason":"Required for model validation.","package":"pydantic","optional":false}],"imports":[{"note":"In v8+, NDArray is exported directly from the package root.","wrong":"from pydantic_numpy.typing import NDArray","symbol":"NDArray","correct":"from pydantic_numpy import NDArray"},{"note":"NumpyModel is now in the root package.","wrong":"from pydantic_numpy.model import NumpyModel","symbol":"NumpyModel","correct":"from pydantic_numpy import NumpyModel"},{"note":"numpy_array is the validated field type, not a function.","wrong":"","symbol":"numpy_array","correct":"from pydantic_numpy import numpy_array"}],"quickstart":{"code":"from pydantic_numpy import NumpyModel, numpy_array\n\nclass MyModel(NumpyModel):\n    data: numpy_array(shape=(3, 4), dtype=float)\n\narray_instance = MyModel(data=[[1.0, 2.0, 3.0, 4.0], [5.0, 6.0, 7.0, 8.0], [9.0, 10.0, 11.0, 12.0]])\nprint(array_instance.data)","lang":"python","description":"Create a Pydantic model with a validated NumPy array field; shape and dtype constraints are enforced."},"warnings":[{"fix":"Update imports to 'from pydantic_numpy import NDArray' and review the migration guide.","message":"Breaking changes between major versions are common. For example, v8 changed the import path of NDArray from pydantic_numpy.typing to pydantic_numpy root. Always check the changelog when upgrading.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Use 'field: numpy_array(...)' inside class definition, not as a function call.","message":"numpy_array is not a function; it's a special form used in type annotations. Attempting to call numpy_array(...) as a function will raise an error.","severity":"gotcha","affected_versions":"all"},{"fix":"Always provide shape as a tuple: shape=(3, 4) not shape=[3, 4].","message":"Shape validation uses tuples; incorrect shape syntax (e.g., using lists) may fail silently or raise unexpected errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Check the latest documentation for current parameter names.","message":"Some older parameter names like 'strict' have been deprecated in favor of 'strict_mode' (or similar) in recent versions.","severity":"deprecated","affected_versions":">=8.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use 'from pydantic_numpy import NDArray'","cause":"Import path changed in v8. NDArray is now in the root package.","error":"ImportError: cannot import name 'NDArray' from 'pydantic_numpy.typing'"},{"fix":"In field annotation, use 'field: numpy_array(shape=(3,4))' not 'field = numpy_array(...)'.","cause":"Misusing numpy_array syntax: numpy_array(shape=(3,4)) where shape is a tuple but used incorrectly as a function.","error":"TypeError: 'tuple' object is not callable"},{"fix":"Use the provided numpy_array type in field annotation.","cause":"Using bare numpy.ndarray as a field type instead of numpy_array.","error":"pydantic.errors.PydanticSchemaGenerationError: Unable to generate schema for <class 'numpy.ndarray'>"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}