Pandas DataFrame.equals() method: Explained with examples

Updated: February 22, 2024 By: Guest Contributor Post a comment


In the realm of data analysis with Python, Pandas stands out for its efficiency and ease of use. Among its myriad functions, the .equals() method is a powerful tool for comparing DataFrames, checking for absolute equality. This guide will dissect the DataFrame.equals() method, providing insights and examples to illustrate its versatility and application.

Basic Example

Let’s start with the simplest form of comparison using the .equals() method. Consider two DataFrames, df1 and df2, comprised of the same data.

import pandas as pd

df1 = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
df2 = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})

This code snippet will output True, indicating that df1 and df2 are exactly the same in terms of structure and data.

Column Order Matters

It’s crucial to realize that the .equals() method checks for both data equality and DataFrame structure, including column order. Observe the following:

df1 = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
df2 = pd.DataFrame({'B': [4, 5, 6], 'A': [1, 2, 3]})

This will return False because, despite having the same data, the column order in df1 and df2 differs.

Index Matters Too

Similarly, the index is a crucial factor in comparison. If two DataFrames have the same data and structure but different indexes, they are considered unequal.

df1 = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]}, index=[1, 2, 3])
df2 = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]}, index=[3, 2, 1])

The output here is False, as the index order impacts the comparison outcome.

Handling NaN Values

Comparing DataFrames containing NaN values can be tricky, as NaN is not equal to NaN by default. However, the .equals() method treats NaNs in both objects as equal, facilitating comparisons involving missing values.

import numpy as np

df1 = pd.DataFrame({'A': [np.nan, 2, np.nan], 'B': [4, np.nan, 6]})
df2 = pd.DataFrame({'A': [np.nan, 2, np.nan], 'B': [4, np.nan, 6]})

This example yields True, demonstrating that the .equals() method is capable of handling NaN values intelligently.

Advanced Example: Comparing Subsets of DataFrames

Occasionally, you might find yourself needing to compare specific portions of DataFrames rather than the entire structure. This can be achieved by slicing or filtering before using the .equals() method. It’s a slightly more advanced technique but incredibly useful for targeted comparisons.

df1 = pd.DataFrame({'A': [1, 2, 3, 4], 'B': [5, 6, 7, 8]})
df2 = pd.DataFrame({'A': [1, 2, 3, 5], 'B': [5, 6, 7, 9]})
filtered_df1 = df1[df1['A'] < 4]
filtered_df2 = df2[df2['A'] < 4]

In this scenario, slicing the DataFrames to compare only rows where column A is less than 4, we receive True, indicating equality in the specified subset, despite the original DataFrames being different.


The .equals() method in Pandas is indispensable for accurately determining the equivalence between two DataFrame objects. It caters to a broad range of scenarios, from simple to complex, ensuring your comparisons are thorough and precise. Understanding its nuances, such as the impact of column order, index, and NaN values, enhances your data analysis toolkit, enabling more reliable and insightful outcomes.