How to Fix Python Pandas User Warning: 'Sorting Because Non-Concatenation Axis is Not Aligned' When Merging DataFrames

Pandas is the cornerstone of data manipulation in Python, enabling users to merge, concatenate, and transform DataFrames with ease. However, even seasoned pandas users encounter warnings that can disrupt workflows and confuse debugging efforts. One such warning is:

UserWarning: Sorting because non-concatenation axis is not aligned. A future version of pandas will change to not sort by default.

If you’ve seen this message, you might have assumed it stems from the pd.merge() function—after all, merging DataFrames is a common task. However, this warning actually originates from pd.concat(), not pd.merge(). This confusion is widespread, so we’ll clarify the root cause, explain why the warning occurs, and provide actionable solutions to resolve it. By the end of this guide, you’ll understand how to eliminate the warning and write more robust pandas code.

Table of Contents#

  1. Understanding the Warning
  2. Why Does This Warning Occur?
  3. Common Scenarios Triggering the Warning
  4. How to Fix the Warning
  5. Best Practices to Avoid the Warning
  6. Conclusion
  7. References

Understanding the Warning#

What’s the Exact Warning?#

The full warning message is:

UserWarning: Sorting because non-concatenation axis is not aligned. A future version of pandas will change to not sort by default.

Where Does It Come From?#

This warning is exclusively emitted by pd.concat(), not pd.merge(). The pd.concat() function combines DataFrames along a specified axis (rows or columns). The "non-concatenation axis" refers to the axis perpendicular to the one you’re concatenating along:

  • If concatenating along rows (axis=0), the "concatenation axis" is rows, and the "non-concatenation axis" is columns.
  • If concatenating along columns (axis=1), the "concatenation axis" is columns, and the "non-concatenation axis" is rows (indexes).

When Does It Trigger?#

The warning appears when:

  • You use pd.concat() with axis=1 (combining DataFrames side-by-side, column-wise).
  • The indexes (row labels) of the input DataFrames are not aligned (i.e., they have different orders or values).

In this case, pandas historically sorted the indexes to align them, ensuring the combined DataFrame has a consistent row order. The warning alerts you that this default sorting behavior will change in future pandas versions (to not sort by default), so you must explicitly control sorting to avoid breaking changes.

Why Does This Warning Occur?#

To understand the warning, let’s dive into pandas’ historical behavior:

  • Before pandas 1.0: When concatenating along columns (axis=1), if the input DataFrames had misaligned indexes, pandas automatically sorted the resulting index to align them. This "helpful" default often hid index misalignment issues.
  • Future pandas versions: To promote explicit code and avoid silent sorting, pandas will stop sorting indexes by default. The warning exists to push users to explicitly specify whether they want sorting (sort=True) or not (sort=False).

In short: The warning is a deprecation notice. It tells you that relying on implicit sorting in pd.concat(axis=1) is unsafe, as future versions will change this behavior.

Common Scenarios Triggering the Warning#

Let’s reproduce the warning with a concrete example. Suppose we have two DataFrames with misaligned indexes and we concatenate them along columns (axis=1):

Example Code:#

import pandas as pd  
 
# Create DataFrame 1 with index [1, 2, 3]  
df1 = pd.DataFrame({"A": [10, 20, 30]}, index=[1, 2, 3])  
 
# Create DataFrame 2 with index [3, 2, 1] (reverse order)  
df2 = pd.DataFrame({"B": [40, 50, 60]}, index=[3, 2, 1])  
 
# Concatenate along columns (axis=1)  
combined = pd.concat([df1, df2], axis=1)

Output:#

UserWarning: Sorting because non-concatenation axis is not aligned. A future version of pandas will change to not sort by default.

Why This Happens:#

df1 has index [1, 2, 3], and df2 has index [3, 2, 1]. When concatenating along columns (axis=1), the non-concatenation axis is the index (rows). Since the indexes are misaligned, pandas sorts them to [1, 2, 3], triggering the warning.

How to Fix the Warning#

Solution 1: Explicitly Set the sort Parameter#

The simplest fix is to explicitly specify the sort parameter in pd.concat(). This tells pandas whether to sort the non-concatenation axis (indexes, when axis=1) and silences the warning.

Syntax:#

pd.concat([df1, df2], axis=1, sort=True)  # Keep pandas' current sorting behavior  
# OR  
pd.concat([df1, df2], axis=1, sort=False)  # Disable sorting (future default)

Example 1: Use sort=True (Replicate Current Behavior)#

If you want to retain pandas’ current behavior (sorting misaligned indexes), set sort=True:

combined = pd.concat([df1, df2], axis=1, sort=True)  
print(combined)

Output (No Warning):#

   A  B  
1 10 60  
2 20 50  
3 30 40

The index is sorted [1, 2, 3], matching the original behavior.

Example 2: Use sort=False (Future-Proof Your Code)#

If you want to disable sorting (the future default), set sort=False. The resulting index will be the union of the input indexes, in the order they appear:

combined = pd.concat([df1, df2], axis=1, sort=False)  
print(combined)

Output (No Warning):#

   A   B  
1 10 NaN  
2 20 NaN  
3 30 40  
2 NaN 50  
1 NaN 60

Here, the index is [1, 2, 3, 2, 1] (the union of df1 and df2 indexes, unsorted). Missing values (NaN) appear where indexes don’t overlap.

Solution 2: Align Indexes Before Concatenation#

If you want to avoid sorting and ensure indexes are aligned, explicitly sort the indexes of the input DataFrames first. This guarantees the non-concatenation axis is aligned, eliminating the need for pandas to sort.

Example:#

# Sort df2's index to match df1's index  
df2_sorted = df2.sort_index()  
 
# Now concatenate with aligned indexes  
combined = pd.concat([df1, df2_sorted], axis=1)  # No warning!  
print(combined)

Output (No Warning):#

   A  B  
1 10 60  
2 20 50  
3 30 40

Since df1 and df2_sorted have identical indexes ([1, 2, 3]), pandas doesn’t need to sort, and the warning is suppressed.

Solution 3: Use DataFrame.join() Instead of pd.concat()#

For column-wise concatenation (axis=1), DataFrame.join() is an alternative to pd.concat(). It aligns DataFrames by index by default and has a sort parameter to control index sorting.

Syntax:#

df1.join(df2, sort=True)  # Sort indexes (matches pd.concat with sort=True)  
# OR  
df1.join(df2, sort=False)  # Do not sort (matches pd.concat with sort=False)

Example:#

combined = df1.join(df2, sort=True)  # Aligns indexes and sorts  
print(combined)

Output (No Warning):#

   A  B  
1 10 60  
2 20 50  
3 30 40

df1.join(df2) is equivalent to pd.concat([df1, df2], axis=1, join='outer') but is more readable for index-based column-wise merging.

Best Practices to Avoid the Warning#

  1. Always Specify sort in pd.concat(axis=1)
    Explicitly set sort=True or sort=False to future-proof your code and avoid the warning. This makes your intent clear to readers and pandas.

  2. Check Indexes Before Concatenation
    Use df.index to inspect indexes. If alignment matters, sort indexes with df.sort_index() before concatenation.

  3. Distinguish merge vs. concat

    • Use pd.merge() to combine DataFrames on shared columns (e.g., merge(df1, df2, on='key')).
    • Use pd.concat() to stack DataFrames along rows/columns (e.g., concat([df1, df2], axis=0) for rows, axis=1 for columns).

  4. Prefer join() for Index-Based Column Merging
    For column-wise combinations aligned by index, df1.join(df2) is more intuitive than pd.concat([df1, df2], axis=1).

Conclusion#

The "Sorting because non-concatenation axis is not aligned" warning is a common pitfall when using pd.concat() with axis=1 (column-wise concatenation). It arises due to misaligned indexes and pandas’ historical default of sorting them. By explicitly setting sort=True/sort=False, aligning indexes, or using DataFrame.join(), you can resolve the warning and write robust, future-proof code.

Remember: This warning is not related to pd.merge(). Always clarify your intent with explicit parameters, and your pandas workflows will be smoother and more predictable.

References#

2025-12