How to Use concat in pandas: Syntax, Examples, and Tips

Use pandas.concat() to combine multiple DataFrames or Series either vertically (rows) or horizontally (columns). You pass a list of objects to concat() and specify axis=0 for rows or axis=1 for columns.

Syntax

The basic syntax of pandas.concat() is:

• objs: A list or dictionary of pandas objects (DataFrames or Series) to concatenate.
• axis: 0 to concatenate vertically (stack rows), 1 to concatenate horizontally (add columns).
• ignore_index: If True, resets the index in the result.
• join: How to handle indexes on other axis, 'outer' (union) or 'inner' (intersection).

python

pandas.concat(objs, axis=0, join='outer', ignore_index=False)

Example

This example shows how to concatenate two DataFrames vertically and horizontally using pandas.concat().

python

import pandas as pd

df1 = pd.DataFrame({'A': ['A0', 'A1'], 'B': ['B0', 'B1']})
df2 = pd.DataFrame({'A': ['A2', 'A3'], 'B': ['B2', 'B3']})

# Concatenate vertically (stack rows)
vertical_concat = pd.concat([df1, df2], axis=0, ignore_index=True)

# Concatenate horizontally (add columns)
horizontal_concat = pd.concat([df1, df2], axis=1)

print('Vertical Concatenation:\n', vertical_concat)
print('\nHorizontal Concatenation:\n', horizontal_concat)

Output

Vertical Concatenation:
     A   B
0  A0  B0
1  A1  B1
2  A2  B2
3  A3  B3

Horizontal Concatenation:
     A   B    A   B
0  A0  B0   A2  B2
1  A1  B1   A3  B3

Common Pitfalls

Common mistakes when using concat() include:

• Not resetting the index after vertical concatenation, which can cause duplicate indexes.
• Concatenating DataFrames with different columns without specifying join, leading to unexpected NaN values.
• Confusing axis=0 (rows) and axis=1 (columns).

python

import pandas as pd

df1 = pd.DataFrame({'A': ['A0', 'A1']})
df2 = pd.DataFrame({'B': ['B0', 'B1']})

# Wrong: default join='outer' adds NaN for missing columns
wrong_concat = pd.concat([df1, df2], axis=0)

# Right: use join='inner' to keep only common columns (none here, so empty)
right_concat = pd.concat([df1, df2], axis=0, join='inner')

print('Wrong concat with NaNs:\n', wrong_concat)
print('\nRight concat with join=inner:\n', right_concat)

Output

Wrong concat with NaNs:
      A    B
0    A0  NaN
1    A1  NaN
0   NaN   B0
1   NaN   B1

Right concat with join=inner:
Empty DataFrame
Columns: []
Index: [0, 1, 0, 1]

Quick Reference

Here is a quick summary of important concat() parameters:

Parameter	Description	Default
objs	List or dict of pandas objects to concatenate	Required
axis	0 to concatenate rows, 1 to concatenate columns	0
join	'outer' for union, 'inner' for intersection of indexes	'outer'
ignore_index	If True, reset index in result	False
keys	Create hierarchical index using keys	None

Key Takeaways

Use pandas.concat() to combine DataFrames or Series along rows (axis=0) or columns (axis=1).

Set ignore_index=True to reset the index after vertical concatenation to avoid duplicate indexes.

Use the join parameter to control how indexes are combined when columns differ.

Remember axis=0 stacks rows; axis=1 adds columns side by side.

Check your data shapes and indexes to avoid unexpected NaN values after concatenation.