{"id":8359,"library":"numpyencoder","title":"NumpyEncoder","description":"NumpyEncoder is a Python JSON encoder designed to seamlessly handle various NumPy data types, including `ndarray`, `np.number`, `np.datetime64`, and more, which are not natively supported by Python's standard `json` module. It extends `json.JSONEncoder` to provide a plug-and-play solution for serializing data structures containing NumPy objects into JSON strings. The current version is 0.3.2, with releases occurring periodically to maintain compatibility with evolving NumPy versions.","status":"active","version":"0.3.2","language":"en","source_language":"en","source_url":"https://github.com/hmallen/numpyencoder","tags":["json","numpy","serialization","encoder","data science"],"install":[{"cmd":"pip install numpyencoder","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core functionality relies on NumPy data types.","package":"numpy","optional":false},{"reason":"Used for dependency management and setup in recent versions (>=0.3.2).","package":"packaging","optional":false}],"imports":[{"symbol":"NumpyEncoder","correct":"from numpyencoder import NumpyEncoder"}],"quickstart":{"code":"import json\nimport numpy as np\nfrom numpyencoder import NumpyEncoder\n\n# Example with a NumPy array and scalar\nnumpy_data = {\n    'array_field': np.array([0, 1.5, 2, 3]),\n    'scalar_field': np.int64(123),\n    'datetime_field': np.datetime64('2023-01-01T12:00:00')\n}\n\n# Serialize the data using NumpyEncoder\njson_output = json.dumps(numpy_data, cls=NumpyEncoder, indent=2)\nprint(json_output)\n\n# The output will convert numpy types to native Python types (lists, int, string for datetime)\nexpected_output_fragment = '\"array_field\": [\n    0.0,\n    1.5,\n    2.0,\n    3.0\n  ],\n  \"scalar_field\": 123,\n  \"datetime_field\": \"2023-01-01T12:00:00\"'","lang":"python","description":"This quickstart demonstrates how to use `NumpyEncoder` to serialize a dictionary containing various NumPy data types (an array, a scalar integer, and a datetime object) into a JSON string. The `cls=NumpyEncoder` argument passed to `json.dumps` ensures that NumPy objects are correctly converted into JSON-serializable Python native types."},"warnings":[{"fix":"Upgrade `numpyencoder` to version 0.3.0 or higher to ensure compatibility with `numpy>=2.0.0`. It is also recommended to review NumPy's 2.0 migration guide for other code adjustments.","message":"NumpyEncoder versions prior to 0.3.0 are not fully compatible with NumPy 2.0.0 due to significant breaking changes in NumPy's API, ABI, and type promotion rules.","severity":"breaking","affected_versions":"<0.3.0"},{"fix":"Be aware of potential precision loss when serializing floating-point NumPy data. For maximum precision, consider using formats like HDF5 (e.g., `h5py`) or NumPy's native binary format (`np.save`, `np.load`) for storing numerical arrays.","message":"Converting NumPy data types (especially floats) to JSON can lead to a loss of precision, as JSON numbers typically follow IEEE 754 double-precision floating-point format. While `numpyencoder` aims for fidelity, critical applications requiring exact precision might consider alternative serialization formats like HDF5 or `.npy`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your NumPy usage adheres to the official NumPy 2.0 migration guide, avoiding deprecated types or patterns, even if `numpyencoder` temporarily supports them for backward compatibility.","message":"NumPy 2.0 introduced deprecations for certain type aliases and internal behaviors. While `numpyencoder` v0.3.2 includes updates to handle these gracefully, relying on deprecated NumPy features directly in your code might lead to future compatibility issues.","severity":"deprecated","affected_versions":"All versions, specifically with `numpy>=2.0.0`"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Use `NumpyEncoder` when calling `json.dumps()`: `json.dumps(your_data, cls=NumpyEncoder)`. This will convert `np.ndarray` objects to Python lists.","cause":"The Python `json` module does not inherently know how to convert NumPy arrays (`numpy.ndarray`) into a JSON-compatible format.","error":"TypeError: Object of type ndarray is not JSON serializable"},{"fix":"Pass `cls=NumpyEncoder` to `json.dumps()`. `NumpyEncoder` handles these scalar NumPy types by converting them to their equivalent Python native types.","cause":"NumPy's scalar types (e.g., `np.int64`, `np.float32`, `np.bool_`) are distinct from Python's native `int`, `float`, or `bool` types and are not directly serializable by the standard `json` module.","error":"TypeError: Object of type int64 is not JSON serializable"},{"fix":"Upgrade `numpyencoder` to version 0.3.0 or higher, which includes specific fixes for NumPy 2.0 compatibility.","cause":"This error occurs in `numpyencoder` when an older version of `numpyencoder` is used with a newer NumPy version (specifically, NumPy 2.0 changed some internal type handling). The `numpy.type` attribute was likely removed or changed.","error":"AttributeError: module 'numpy' has no attribute 'type'"}]}