---
id: pydantic-numpy
version: "9.0.2"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# pydantic-numpy — Pydantic Model integration of the NumPy array

License: permissive · Maintenance: active · Downloads: 178.4K/mo

## 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 above — 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

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

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 178.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

numpy array pydantic validation, pydantic numpy integration, typed numpy arrays, serialize numpy arrays json, pydantic numpy models, numpy dtype validation, array dimension checking, numpy-integration, data-validation, serialization

[View on SkillFed](https://skillfed.io/packages/pydantic-numpy) · [View on PyPI](https://pypi.org/project/pydantic-numpy/)