Registry / serialization / pydantic-numpy

pydantic-numpy

library9.0.1pypypiunverified

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.

serialization data ai-ml

pip install pydantic-numpy

github ↗package ↗

INSTALL

IMPORT

SIG · PYDANTIC-NUMPY

pydantic-numpy

serializationpythonv9.0.1

Install

6.0s avg

Import

—

Disk

107MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v8.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 6.0s · import 0.000s · 105MB

107MB installed

● package 107MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

NDArray

✓ from pydantic_numpy import NDArray

✗ from pydantic_numpy import NDArray

Create a Pydantic model with a validated NumPy array field; shape and dtype constraints are enforced.

from pydantic_numpy import NumpyModel, numpy_array class MyModel(NumpyModel): data: numpy_array(shape=(3, 4), dtype=float) array_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]]) print(array_instance.data)

Debug

Known issues

breakingBreaking 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.

fix

Update imports to 'from pydantic_numpy import NDArray' and review the migration guide.

affects: >=8.0.0

gotchanumpy_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.

fix

Use 'field: numpy_array(...)' inside class definition, not as a function call.

affects: all

gotchaShape validation uses tuples; incorrect shape syntax (e.g., using lists) may fail silently or raise unexpected errors.

fix

Always provide shape as a tuple: shape=(3, 4) not shape=[3, 4].

affects: all

deprecatedSome older parameter names like 'strict' have been deprecated in favor of 'strict_mode' (or similar) in recent versions.

fix

Check the latest documentation for current parameter names.

affects: >=8.0.0

Upgrade

Version history

9.0.1latest on PyPI · released Dec 5, 2025

Audit

Dependencies

numpyrequiredCore dependency for array data types.

pydanticrequiredRequired for model validation.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/caniko/pydantic-numpy ↗

packagehttps://pypi.org/project/pydantic-numpy/ ↗