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.

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 ==.
x = float('nan')
print(x == x) # False
print(x == float('nan')) # False
print(x != x) # TrueThis 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.
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.
| Method | Works on | Readability |
|---|---|---|
math.isnan(x) | Single float | High |
x != x | Single float | Low |
numpy.isnan(x) | Arrays and scalars | Medium |
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.
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:
x = float('nan')
print(x + 1) # nan
print(x * 0) # nan
print(x / 1) # nanComparisons 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.
print(1.0 < float('nan')) # False
print(1.0 > float('nan')) # False
print(1.0 == float('nan')) # FalseIn 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.
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.0In 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().
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 0When 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.
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:
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.
import numpy as np
arr = np.array([1.0, np.nan, 3.0])
print(np.mean(arr)) # nan
print(np.nanmean(arr)) # 2.0These 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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.