Skip to main content
`Ctrl`+`K`

# numpy.insert

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

  Insert values along the given axis before the given indices.

  Parameters:
    arr array_like

      Input array.

    obj slice, int, array-like of ints or bools

      Object that defines the index or indices before which values is inserted.

      Changed in version 2.1.2: Boolean indices are now treated as a mask of elements to insert, rather than being cast to the integers 0 and 1.

      Support for multiple insertions when obj is a single scalar or a sequence with one element (similar to calling insert multiple times).

    values array_like

      Values to insert into arr. If the type of values is different from that of arr, values is converted to the type of arr. values should be shaped so that `arr[...,obj,...] = values` is legal.

    axis int, optional

      Axis along which to insert values. If axis is None then arr is flattened first.

  Returns:
    out ndarray

      A copy of arr with values inserted. Note that `insert` does not occur in-place: a new array is returned. If axis is None, out is a flattened array.

  See also

  `append`

    Append elements at the end of an array.

  `concatenate`

    Join a sequence of arrays along an existing axis.

  `delete`

    Delete elements from an array.

  Notes

  Note that for higher dimensional inserts `obj=0` behaves very different from `obj=[0]` just like `arr[:,0,:] = values` is different from `arr[:,[0],:] = values`. This is because of the difference between basic and advanced indexing.

  Examples

      >>> import numpy as np
      >>> a = np.arange(6).reshape(3, 2)
      >>> a
      array([[0, 1],
             [2, 3],
             [4, 5]])
      >>> np.insert(a, 1, 6)
      array([0, 6, 1, 2, 3, 4, 5])
      >>> np.insert(a, 1, 6, axis=1)
      array([[0, 6, 1],
             [2, 6, 3],
             [4, 6, 5]])

  Difference between sequence and scalars, showing how `obj=[1]` behaves different from `obj=1`:

      >>> np.insert(a, [1], [[7],[8],[9]], axis=1)
      array([[0, 7, 1],
             [2, 8, 3],
             [4, 9, 5]])
      >>> np.insert(a, 1, [[7],[8],[9]], axis=1)
      array([[0, 7, 8, 9, 1],
             [2, 7, 8, 9, 3],
             [4, 7, 8, 9, 5]])
      >>> np.array_equal(np.insert(a, 1, [7, 8, 9], axis=1),
      ...                np.insert(a, [1], [[7],[8],[9]], axis=1))
      True

      >>> b = a.flatten()
      >>> b
      array([0, 1, 2, 3, 4, 5])
      >>> np.insert(b, [2, 2], [6, 7])
      array([0, 1, 6, 7, 2, 3, 4, 5])

      >>> np.insert(b, slice(2, 4), [7, 8])
      array([0, 1, 7, 2, 8, 3, 4, 5])

      >>> np.insert(b, [2, 2], [7.13, False]) # type casting
      array([0, 1, 7, 0, 2, 3, 4, 5])

      >>> x = np.arange(8).reshape(2, 4)
      >>> idx = (1, 3)
      >>> np.insert(x, idx, 999, axis=1)
      array([[  0, 999,   1,   2, 999,   3],
             [  4, 999,   5,   6, 999,   7]])