pydantic-numpy

What it is and what it does

pydantic-numpy bridges NumPy arrays and Pydantic's validation and serialization framework. It provides typed annotations (like NpNDArrayFp64 for 3D float64 arrays) that work with both BaseModel and dataclass, plus a NumpyModel class for seamless dump/load of arrays to disk. You can instantiate models from raw arrays, NumPy .npy files, or .npz files with keys, and serialize to JSON with full schema compliance.

The package handles the impedance mismatch between NumPy's array semantics and Pydantic's type system by wrapping arrays in validated fields. It supports custom serialization, dimension constraints, dtype specification, and model-agnostic loading when multiple models might match. Runtime dependencies are minimal and well-established (pydantic, numpy, ruamel-yaml, compress-pickle, semver).

Use it for:

• Validate and serialize machine-learning model inputs/outputs that include NumPy arrays as Pydantic models.
• Define strict dtype and dimension requirements for arrays in data pipelines (e.g., float32 1D arrays only).
• Persist Pydantic models containing arrays to disk and reload them with automatic type checking.
• Generate JSON schemas for APIs that accept or return NumPy array data.
• Combine NumPy arrays with other Pydantic fields in a single validated data structure.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Integrates NumPy arrays into Pydantic models with type validation, allowing you to define, validate, serialize, and deserialize NumPy arrays as model fields.

Yes. The package is actively maintained, has no known vulnerabilities, low install friction, and solves a real gap in Pydantic's NumPy support. It's suitable for production use if you need to validate and serialize NumPy arrays within Pydantic models. The permissive BSD-3-Clause license poses no restriction.

Install

pydantic-numpy on PyPI

pip install pydantic-numpy

uv add pydantic-numpy

poetry add pydantic-numpy

Installing pydantic-numpy

Before you install

Low friction install with five runtime dependencies (pydantic, numpy, ruamel-yaml, compress-pickle, semver). Active maintenance with a release 13 days ago; repo is not archived and has recent commits.

License in practice

BSD-3-Clause is permissive; you can use, modify, and distribute this package with minimal restrictions in commercial or open-source projects.

Quickstart

pip install pydantic-numpy

import numpy as np
from pydantic import BaseModel
import pydantic_numpy.typing as pnd

class MyModel(BaseModel):
    array: pnd.Np1DArrayFp64

model = MyModel(array=np.array([1.5, 2.5, 3.5]))
json_str = model.model_dump_json()
restored = MyModel.model_validate_json(json_str)

Requires Python 3.11 or later (supports current versions, <3.15).

Verify before relying

• Whether custom serialization functions can handle all array types and edge cases you need.
• Performance characteristics when working with very large arrays or deeply nested structures.
• Compatibility with all Pydantic v2 features beyond the examples shown.

Package facts

Evidence: pydantic_numpy-9.0.2-py3-none-any.whl

Keywords: pydantic, numpy, typing, validation

Tags

More Python Modules packages