Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Float NaN: Detection and Handling

How Python float NaN behaves, why it never equals itself, and how to detect and handle NaN in data processing, serialization, and numerical computations.

~4 min readPython
#NaN#floating-point#math.isnan#data cleaning
A visual representation of a floating-point number with a missing piece, symbolizing NaN in Python.

Python floats can hold a special value called NaN (Not a Number). It is used to represent missing or undefined numeric results, but it behaves differently from ordinary numbers: it never compares equal to itself, and it can silently affect aggregations and serialized data. This article explains where NaN comes from, how to detect it reliably, and how to handle it in data processing, JSON serialization, and numerical libraries.

What NaN Is and Where It Comes From

NaN appears when a floating-point operation has no meaningful numeric result, such as float('inf') / float('inf'), or when you explicitly create it with float('nan'). Note that 0.0 / 0.0 raises a ZeroDivisionError in Python instead of returning NaN. NaN can also appear when parsing data: float('nan') succeeds, while float('not-a-number') raises a ValueError. In datasets, NaN often represents missing or malformed values.

NaN is defined by the IEEE 754 floating-point standard. It is not a single value; many bit patterns can represent NaN. In Python, all of them behave the same way in arithmetic and comparisons.

Why NaN Never Equals Itself

The most surprising behavior of NaN is that it is not equal to itself. x == float('nan') is always False, even if x is also NaN. This is not a Python quirk; it is part of the IEEE 754 specification. NaN represents an undefined result, so equality and ordering comparisons involving it are False; != returns True because it is the negation of ==.

python
x = float('nan') print(x == x) # False print(x == float('nan')) # False print(x != x) # True

This behavior breaks code that relies on equality to detect NaN. A common idiom is value != value, but it is less readable than using math.isnan.

Detecting NaN with math.isnan and Alternatives

The standard library provides math.isnan() to check for NaN. It is the most explicit and readable way.

python
import math value = float('nan') if math.isnan(value): print("value is NaN")

There are two other common approaches: the x != x trick and numpy.isnan() when working with arrays.

MethodWorks onReadability
math.isnan(x)Single floatHigh
x != xSingle floatLow
numpy.isnan(x)Arrays and scalarsMedium

For scalar values, math.isnan is preferred because it is explicit and self-documenting. The x != x trick is concise but obscure; it can be useful when you want to avoid an import. numpy.isnan is essential when an array needs a boolean mask of the same shape.

python
import numpy as np arr = np.array([1.0, np.nan, 3.0]) mask = np.isnan(arr) print(mask) # [False True False]

How NaN Behaves in Arithmetic and Comparisons

Arithmetic in Python generally propagates NaN: once a value becomes NaN, later ordinary operations on it usually remain NaN. For example:

python
x = float('nan') print(x + 1) # nan print(x * 0) # nan print(x / 1) # nan

Comparisons with NaN are also problematic. All ordered comparisons (<, >, <=, >=) return False when either operand is NaN. This means NaN is neither less than, greater than, nor equal to any number, including itself. This can break sorting and searching algorithms that assume a total order.

python
print(1.0 < float('nan')) # False print(1.0 > float('nan')) # False print(1.0 == float('nan')) # False

In practice, if you sort a list containing NaN, the position of NaN is not guaranteed because its comparison results are all False; different inputs or implementations can place it in different positions. Filter it out before sorting or use a key function that assigns a stable value.

Handling NaN in Data Processing

When processing data, NaN values can cause silent failures in aggregate operations. For example, sum([1.0, float('nan'), 2.0]) returns nan, and min and max may return surprising results because NaN comparisons are always false. The standard library's math module does not provide a NaN-aware sum, but you can filter NaN values explicitly.

python
import math values = [1.0, float('nan'), 2.0, 3.0] clean = [v for v in values if not math.isnan(v)] print(sum(clean)) # 6.0

In larger data pipelines, libraries like pandas handle NaN more systematically. Pandas uses NaN to represent missing values, and its aggregation methods accept a skipna parameter (defaulting to True). For example, df['column'].mean() ignores NaN by default. If you need to replace NaN with a sentinel value, use fillna().

python
import pandas as pd df = pd.DataFrame({'value': [1.0, None, 3.0]}) print(df['value'].mean()) # 2.0 print(df['value'].fillna(0)) # replaces NaN with 0

When writing custom data processing code, decide explicitly whether NaN should be propagated, filtered, or replaced. Propagating NaN can be useful to signal invalid results, but it often leads to confusing downstream behavior. Filtering is appropriate when missing values are not meaningful. Replacing with a default value is useful when you have a sensible fallback.

NaN and JSON Serialization

NaN is not part of the JSON specification. Python's json module, by default, serializes float('nan') as NaN, which is not valid JSON. This can cause interoperability issues with systems that expect strict JSON.

python
import json data = {'value': float('nan')} print(json.dumps(data)) # {"value": NaN} (not valid JSON)

One option is allow_nan=False in json.dumps(), which raises a ValueError if NaN is encountered. Another is to clean the values before serialization. For example, convert NaN to None explicitly:

python
import math import json data = {'value': float('nan')} clean_data = { key: (None if isinstance(value, float) and math.isnan(value) else value) for key, value in data.items() } print(json.dumps(clean_data)) # {"value": null}

The right choice depends on your use case. If the receiving system expects null for missing values, converting NaN to None is often appropriate. If you need to preserve the distinction between missing and invalid, use a documented string convention before serialization.

NaN in Numerical Computations

In scientific computing, NaN can corrupt entire calculations if not handled correctly. For example, numpy.mean() on an array containing NaN returns nan by default. NumPy provides NaN-aware variants such as np.nansum, np.nanmean, and np.nanmax that ignore NaN values.

python
import numpy as np arr = np.array([1.0, np.nan, 3.0]) print(np.mean(arr)) # nan print(np.nanmean(arr)) # 2.0

These functions are useful when working with real-world datasets that contain missing values. They check for NaN on each element, so the regular functions are simpler when you are certain the data has no NaN; if NaN is possible, the NaN-aware versions are safer and more readable than manually filtering the array.

In pandas, the same principle applies through the skipna parameter. By default, most pandas aggregations skip NaN. If you need to include NaN in calculations, set skipna=False, but this usually returns NaN.

Understanding how NaN behaves in Python floats is not just about knowing the syntax; it is about making deliberate decisions in your code. Whether you filter, replace, or propagate NaN, the key is to be explicit and consistent so that your data pipeline behaves predictably.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.