Fix int64 JSON Serialization Error

Understanding the int64 JSON Error

Python's JSON module cannot handle NumPy data types like int64 by default. This error appears when you try to convert a NumPy integer to JSON format. It's a common issue for data scientists and developers working with NumPy arrays and JSON serialization.

The error message looks like this:

TypeError: Object of type int64 is not JSON serializable

Why This Error Occurs

Python's json module only supports native Python types. These include int, float, str, list, dict, bool, and None. NumPy integers like int64 are not part of this group.

When you use json.dumps() on a Python object containing NumPy integers, the encoder fails. It doesn't know how to convert int64 to a JSON-compatible format.

Simple Example of the Error

Let's see the error in action:

import numpy as np
import json

# Create a NumPy integer
data = {
    "age": np.int64(25),
    "name": "Alice"
}

# This will raise a TypeError
json_string = json.dumps(data)
print(json_string)

Running this code produces:

TypeError: Object of type int64 is not JSON serializable

Solution 1: Convert to Native Python Types

The simplest fix is to convert NumPy types to Python native types before serialization. Use the .item() method to convert a NumPy scalar to a Python scalar.

import numpy as np
import json

data = {
    "age": np.int64(25).item(),  # Convert to Python int
    "name": "Alice"
}

json_string = json.dumps(data)
print(json_string)

Output:

{"age": 25, "name": "Alice"}

Solution 2: Use a Custom JSON Encoder

For complex data structures, create a custom JSON encoder class. This approach handles all NumPy types in one place.

import numpy as np
import json

class NumpyEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, (np.int_, np.intc, np.intp, np.int8,
            np.int16, np.int32, np.int64, np.uint8,
            np.uint16, np.uint32, np.uint64)):
            return int(obj)
        elif isinstance(obj, (np.float_, np.float16, np.float32, np.float64)):
            return float(obj)
        elif isinstance(obj, (np.ndarray,)):
            return obj.tolist()
        return super().default(obj)

data = {
    "age": np.int64(25),
    "score": np.float64(95.5),
    "scores": np.array([1, 2, 3])
}

json_string = json.dumps(data, cls=NumpyEncoder)
print(json_string)

Output:

{"age": 25, "score": 95.5, "scores": [1, 2, 3]}

Solution 3: Use the default Parameter

You can pass a custom function to the default parameter of json.dumps(). This is quick for simple cases.

import numpy as np
import json

def convert_numpy(obj):
    if isinstance(obj, (np.integer,)):
        return int(obj)
    elif isinstance(obj, (np.floating,)):
        return float(obj)
    elif isinstance(obj, (np.ndarray,)):
        return obj.tolist()
    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")

data = {
    "age": np.int64(25),
    "weight": np.float64(70.5)
}

json_string = json.dumps(data, default=convert_numpy)
print(json_string)

Output:

{"age": 25, "weight": 70.5}

Solution 4: Use Pandas to_json()

If you work with pandas DataFrames, use the built-in to_json() method. It handles NumPy types automatically.

import pandas as pd
import numpy as np

df = pd.DataFrame({
    "age": [np.int64(25), np.int64(30)],
    "name": ["Alice", "Bob"]
})

json_string = df.to_json(orient="records")
print(json_string)

Output:

[{"age":25,"name":"Alice"},{"age":30,"name":"Bob"}]

Common Scenarios and Fixes

Scenario 1: You have a dictionary with mixed Python and NumPy types. Use the custom encoder approach to handle all types.

Scenario 2: You are working with large NumPy arrays. Convert them to lists using .tolist() before serialization.

Scenario 3: You use machine learning libraries that return NumPy predictions. Always convert predictions to Python types before saving as JSON.

Best Practices to Avoid This Error

Always check your data types before JSON serialization. Use type() to inspect values. For example:

import numpy as np

value = np.int64(42)
print(type(value))  # 

# Convert before serialization
safe_value = value.item()
print(type(safe_value))  # 

Consider using a library like simplejson that may handle some conversions. But the safest approach is explicit conversion.

For more detailed guidance on Python type errors, check out our article on Python TypeError: Causes and Fixes.

Conclusion

The TypeError: object of type int64 is not JSON serializable is easy to fix. Convert NumPy integers to Python native integers using .item(), create a custom JSON encoder, or use the default parameter in json.dumps(). Always verify your data types before serialization to avoid runtime errors. With these solutions, you can handle NumPy types in JSON operations smoothly.

Remember to test your code with sample data to ensure all types are correctly converted. This saves debugging time and makes your code more robust.