NumPy insert(): Insert Values at Given Index Position & Axis

Note that insert() always returns a copy of the input array rather than modifying the original array in place. If no axis is specified, the input array is flattened prior to insertion. For related structural array modifications, review append() and reshape().

Syntax and Parameters 🔝

numpy.insert(arr, obj, values, axis=None)

Code Block Modernization Comparison 🔝

Review how legacy NumPy insert snippets compare against the modernized, structured, and self-verifying implementation:

Basic 1D Insertion 🔝

Insert a single value at a specified index position in a 1D array. Note that the original array remains unchanged as insert() returns a new copy:

import numpy as np

npr = np.array([5, 8, 3])
npr1 = np.insert(npr, 1, 10) # Insert 10 at index position 1

print("Original array:", npr)   # [5 8 3] (unchanged)
print("Inserted array:", npr1)  # [ 5 10  8  3]

assert np.array_equal(npr, np.array([5, 8, 3]))
assert np.array_equal(npr1, np.array([5, 10, 8, 3]))

Expected output

Original array: [5 8 3]
Inserted array: [ 5 10  8  3]

Inserting at the End 🔝

You can append an element at the end of the array by setting the insertion index to len(arr):

npr = np.array([5, 8, 3])
npr1 = np.insert(npr, len(npr), 10)

print("Inserted at end:", npr1) # [ 5  8  3 10]
assert npr1[-1] == 10

Expected output

Inserted at end: [ 5  8  3 10]

2D Array Insertion & Shape Rules 🔝

When an axis is provided, the inserted values must be broadcast-compatible with the dimensions of the array. Mismatched shapes will raise a ValueError:

npr = np.array([
    [0, 1, 2, 4],
    [3, 4, 5, 6],
    [6, 7, 8, 9]
])

# Insert a row along axis=0
npr1 = np.insert(npr, 1, [10, 11, 12, 13], axis=0)
print("Inserted row:
", npr1)

assert npr1.shape == (4, 4)

Expected output

Inserted row:
 [[ 0  1  2  4]
 [10 11 12 13]
 [ 3  4  5  6]
 [ 6  7  8  9]]

Axis Direction & Multiple Indices 🔝

You can insert columns along axis=1 or specify multiple insertion indices simultaneously:

npr = np.array([
    [0, 1, 2, 4],
    [3, 4, 5, 6],
    [6, 7, 8, 9]
])

# Insert column along axis=1
npr_col = np.insert(npr, 1, [10, 11, 12], axis=1)
print("Inserted column:
", npr_col)

assert npr_col.shape == (3, 5)

Expected output

Inserted column:
 [[ 0 10  1  2  4]
 [ 3 11  4  5  6]
 [ 6 12  7  8  9]]

Flattened Insertion without Axis 🔝

If axis is omitted, NumPy flattens the multi-dimensional array before performing the insertion:

npr = np.array([
    [0, 1, 2, 4],
    [3, 4, 5, 6],
    [6, 7, 8, 9]
])

npr_flat = np.insert(npr, 1, [10, 11, 12])
print("Flattened insertion result:
", npr_flat)
assert npr_flat.ndim == 1

Expected output

Flattened insertion result:
 [ 0 10 11 12  1  2  4  3  4  5  6  6  7  8  9]

Practice in Google Colab 🔝

Test array insertions, axis specifications, shape broadcasting rules, and run verification test suites in our interactive Google Colab companion notebook:

Interactive Practice: Colab & GitHub

Launch the notebook directly in Google Colab to run live code cells or inspect the source repository on GitHub:

View on GitHub

Continue exploring related array manipulation functions: array(), append(), array_split(), and reshape().

Subhendu Mohapatra

Author & Instructor at plus2net

I write and maintain practical tutorials on Python, PHP, SQL, JavaScript, HTML, jQuery, and web development at plus2net. The tutorials focus on clear explanations, working examples, and code that readers can test and adapt while learning.

About the author   Watch on YouTube

Connect: