Pandas Concatenating Data
last modified November 17, 2026 Python 3.15
Concatenation means joining tables end to end. Pandas' pd.concat takes a list of Series or DataFrames and stacks them, either on top of one another or side by side. It is the tool to reach for when the pieces hold the same kind of data — for example, monthly sales figures that should become one table.
Unlike a database-style join, concatenation does not look for matching keys; it simply lines up rows or columns and fills gaps with missing values. All examples below were verified with pandas 3.1.1. For combining tables on a shared key see Pandas merging data.
Stacking rows with axis=0
The axis parameter says along which direction to stack. The default, axis=0, appends rows: the second frame is placed below the first and the column labels are aligned. Because both frames here use labels 0 and 1, those labels are repeated in the result.
import pandas as pd
df1 = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
df2 = pd.DataFrame({'a': [5, 6], 'b': [7, 8]})
print(pd.concat([df1, df2]))
The four rows appear in order, with columns a and b from both frames. The index reads 0, 1, 0, 1 — Pandas does not try to make the labels unique. That is often fine, but the next section shows how to renumber them.
$ python concat_rows.py a b 0 1 3 1 2 4 0 5 7 1 6 8
Stacking columns with axis=1
With axis=1, frames are placed side by side: their columns are combined and rows are matched by index label. The two frames here share the index 0 and 1, so their single columns end up next to each other in one row-indexed table.
import pandas as pd
df1 = pd.DataFrame({'a': [1, 2]})
df2 = pd.DataFrame({'b': [3, 4]})
print(pd.concat([df1, df2], axis=1))
The result has the two columns a and b and still only two rows. If the inputs had different index labels, the rows would be aligned by label and missing combinations would be filled with NaN.
$ python concat_columns.py a b 0 1 3 1 2 4
Resetting the index with ignore_index
The repeated labels from the first example can make a combined table awkward to work with. ignore_index=True throws away the incoming labels and builds a fresh index numbered from zero. It is the concatenation equivalent of the same option on drop_duplicates.
import pandas as pd
df1 = pd.DataFrame({'a': [1, 2]})
df2 = pd.DataFrame({'a': [3, 4]})
print("default:")
print(pd.concat([df1, df2]))
print()
print("ignore_index=True:")
print(pd.concat([df1, df2], ignore_index=True))
The default output repeats 0 and 1, which could be confusing if you later select by label. With ignore_index=True the four rows are numbered 0 through 3. The values are unchanged.
$ python concat_ignore_index.py default: a 0 1 1 2 0 3 1 4 ignore_index=True: a 0 1 1 2 2 3 3 4
Inner and outer joins on columns
When the inputs do not have exactly the same columns, join decides what happens to the extras. The default, join='outer', keeps every column from every frame and fills absent values with NaN. join='inner' keeps only the columns present in all inputs.
import pandas as pd
df1 = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
df2 = pd.DataFrame({'a': [5, 6], 'c': [7, 8]})
print("outer (default):")
print(pd.concat([df1, df2]))
print()
print("inner:")
print(pd.concat([df1, df2], join='inner'))
The outer result has three columns: a appears in both frames, while b and c each appear in only one, producing NaN in the other rows. The inner result keeps only the shared column a, so all four rows have a value.
$ python concat_join.py outer (default): a b c 0 1 3.0 NaN 1 2 4.0 NaN 0 5 NaN 7.0 1 6 NaN 8.0 inner: a 0 1 1 2 0 5 1 6
Labelling the source with keys
The keys parameter attaches a label to each input frame. Those labels become an extra index level above the original row numbers, producing a MultiIndex — an index made of more than one level. It lets you tell afterwards which frame each row came from.
import pandas as pd
df1 = pd.DataFrame({'a': [1, 2]})
df2 = pd.DataFrame({'a': [3, 4]})
result = pd.concat([df1, df2], keys=['first', 'second'])
print(result)
print()
print(result.index)
The printed index has two levels: first and second from the keys, and the original row numbers 0 and 1 beneath them. The explicit result.index line shows the four resulting pairs as a MultiIndex.
$ python concat_keys.py
a
first 0 1
1 2
second 0 3
1 4
MultiIndex([( 'first', 0),
( 'first', 1),
('second', 0),
('second', 1)],
)
Checking for duplicate labels with verify_integrity
A duplicate label is an index value that appears more than once. Ordinarily concat allows this, as the first example showed. Setting verify_integrity=True makes it raise a ValueError if the combined index would contain any repeated label, which is a useful safety check when labels should be unique.
import pandas as pd
df1 = pd.DataFrame({'a': [1, 2]}, index=[0, 1])
df2 = pd.DataFrame({'a': [3, 4]}, index=[1, 2])
print("without verify_integrity:")
print(pd.concat([df1, df2]))
print()
try:
pd.concat([df1, df2], verify_integrity=True)
except ValueError as e:
print("with verify_integrity=True, ValueError raised:")
print(e)
Without the check, label 1 appears twice and the concatenation succeeds. With verify_integrity=True, Pandas reports that the indexes have overlapping values and shows the offending label 1. The example catches the error so the script can print it neatly.
$ python verify_integrity.py without verify_integrity: a 0 1 1 2 1 3 2 4 with verify_integrity=True, ValueError raised: Indexes have overlapping values: Index([1], dtype='int64')
The removed append method
Older Pandas code often used DataFrame.append to add one frame to another. That method was deprecated in pandas 1.4 and removed in pandas 2.0; calling it now raises an AttributeError. The replacement is pd.concat with a list, which is what all of the examples above use.
import pandas as pd
print("DataFrame.append exists:", hasattr(pd.DataFrame, 'append'))
The check returns False: there is no append method on DataFrame in pandas 3.1.1. Code such as df.append(other) should be rewritten as pd.concat([df, other]), optionally with ignore_index=True.
$ python removed_append.py DataFrame.append exists: False
Concatenation versus merging
Concatenation and merging solve different problems. Concatenation stacks whole tables and aligns them by position or index; merging uses a shared key column to line up related records, like a SQL join. Use concat for more rows of the same data and merge for adding columns from another table based on a key.
import pandas as pd
left = pd.DataFrame({'id': [1, 2], 'name': ['Alice', 'Bob']})
right = pd.DataFrame({'id': [1, 2], 'score': [85, 90]})
print(pd.merge(left, right, on='id'))
Here merge matches rows where the id values agree and brings the name and score columns together in one row per id. Concatenating these two frames instead would simply stack six rows and pad the missing cells with NaN. See Pandas merging data for the full range of merge options.
$ python concat_vs_merge.py id name score 0 1 Alice 85 1 2 Bob 90
Source
Pandas concat Documentation, Pandas Merge, join, concatenate and compare Documentation, and Pandas 2.0 release notes
In this article we have stacked DataFrames along both axes, reset the index, chosen inner or outer column alignment, labelled inputs with keys to build a MultiIndex, guarded against duplicate labels with verify_integrity, noted the removal of append, and compared concatenation with merging. For combining tables on a key see Pandas merging data, and for index-based joins see Pandas join function.
Author
List all Pandas tutorials.