Pandas dataframe.insert()-Python

DataFrame.insert() function in pandas inserts a new column into a DataFrame at a specified position. It allows you to specify the column index, column label and values to insert. This is particularly useful when you want to place a new column in a specific position instead of just appending it at the end.

For example:

import pandas as pd
df = pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
df.insert(1, 'C', [5, 6])

print(df)

   A  C  B
0  1  5  3
1  2  6  4

Explanation: df.insert(1, 'C', [5, 6]) inserts the column 'C' at index position 1 with the values [5, 6]. Existing columns are shifted to the right.

Syntax

DataFrame.insert(loc, column, value, allow_duplicates=False)

Parameters:

• loc (int): Position (0-based index) where the new column should be inserted.
• column (str): Label for the new column.
• value (array-like, scalar or Series): Values to insert can be a scalar, list, NumPy array or a pandas Series.
• allow_duplicates (bool, default=False): If set to False, raises an error if a column with the same name already exists.

Returns: Modifies the DataFrame in-place and does not return a new DataFrame.

Examples

Example 1: In this example, we insert a new column at index 1. Since the value is a scalar, it is broadcasted to all rows.

import pandas as pd
df = pd.DataFrame({'A': [1, 2]})
df.insert(1, 'B', 100)

print(df)

   A    B
0  1  100
1  2  100

Explanation: Inserts a new column 'B' at index 1. Since value is a scalar, it fills all rows with 100.

Example 2: Here, we already have a column 'A' and we attempt to insert another column with the same name. This works only because we explicitly allow duplicates.

import pandas as pd
df = pd.DataFrame({'A': [1, 2]})
df.insert(1, 'A', [3, 4], allow_duplicates=True)

print(df)

   A  A
0  1  3
1  2  4

Explanation: Inserts a new column named 'A' despite it already existing. Allowed by setting allow_duplicates=True.

Example 3: In this example, we insert column at position 0. All existing columns are shifted to the right.

import pandas as pd
df = pd.DataFrame({'B': [10, 20], 'C': [30, 40]})
df.insert(0, 'A', [1, 2])

print(df)

   A   B   C
0  1  10  30
1  2  20  40

Explanation: df.insert(0, 'A', [1, 2]) inserts a new column 'A' at index position 0, which means it appears at the beginning of the DataFrame. All existing columns ('B' and 'C') are shifted one position to the right to make space.

Example 4: This shows how to insert a column at the end using len(df.columns) as the position.

import pandas as pd
df = pd.DataFrame({'X': [1, 2]})
df.insert(len(df.columns), 'Y', [9, 8])

print(df)

   X  Y
0  1  9
1  2  8

Explanation: df.insert(len(df.columns), 'Y', [9, 8]) inserts the new column 'Y' at the end of the DataFrame by specifying the current number of columns as the insert position.

Example 5: This example demonstrates inserting a column by passing a Series object. The values are aligned with the DataFrame’s index.

import pandas as pd
df = pd.DataFrame({'A': [10, 20, 30]})
s = pd.Series([100, 200, 300], index=[0, 1, 2])
df.insert(1, 'B', s)

print(df)

    A    B
0  10  100
1  20  200
2  30  300

Explanation: df.insert(1, 'B', s) inserts this Series as a new column 'B' at index 1. The values from the Series align with the DataFrame rows based on their index.

Example 6: This example shows that trying to insert a column with an existing name without setting allow_duplicates=True results in an error.

import pandas as pd
df = pd.DataFrame({'A': [1, 2]})
df.insert(1, 'A', [3, 4])

Output

File "/usr/local/lib/python3.13/site-packages/pandas/core/frame.py", line 5158, in insert
raise ValueError(f"cannot insert {column}, already exists")
ValueError: cannot insert A, already exists

Explanation: By default, insert() does not allow duplicate column names and raises an error unless allow_duplicates=True is set.

Related articles

• Pandas
• Pandas series