NumPy Tutorial - NumPy Array Append

NumPy provides numpy.append to add values to an array. It is a function, not an ndarray.append method, and it returns a new array rather than changing the input array in place. Python lists use methods with related names: list.append adds one object as a single item, while list.extend adds each item from an iterable. NumPy’s function instead follows array shape and axis rules, so the list operations are useful comparisons, not interchangeable calls.

What numpy.append does

numpy.append combines an input array with values and returns the combined result. By default it flattens both inputs first, so the result is one-dimensional even if the original arrays had multiple dimensions. Supplying an axis preserves the other dimensions and joins along that direction. Choose the default when you want a flat sequence; choose an axis when the row and column arrangement matters.

Because the function returns a new array, keep its return value if you need the combined result. For example, assign it to a new variable or reassign the original variable. Calling the function without using its return value does not update arr.

Syntax and parameters

The signature is numpy.append(arr, values, axis=None) (commonly called as np.append after importing NumPy as np). arr is the array-like input to extend. values contains the data to add and may be a scalar or array-like object. axis selects the dimension along which to join; its default, None, flattens both inputs before joining. The function returns an array.

Run this example:

import numpy as np

numbers = np.array([1, 2, 3])
combined = np.append(numbers, [4, 5])
print(combined)

[1 2 3 4 5]

Append without an axis

When axis is omitted or set to None, NumPy flattens arr and values before joining them. The result is one-dimensional, regardless of the inputs’ original dimensions. For instance, a two-dimensional array can be combined with a row of values without preserving rows and columns. This behavior is convenient for making a flat sequence, but it does not insert a row or column into the original layout.

If preserving the array’s dimensions is important, specify an axis instead of relying on the default. Flattening can make inputs with different shapes usable together because their dimensions are discarded before the values are combined.

Append along an axis

For a two-dimensional array, axis=0 adds rows and axis=1 adds columns. The input shapes must match on every dimension other than the one being joined. Thus, adding a row requires its column count to match the existing array; adding a column requires its row count to match. A mismatch raises ValueError because the arrays cannot be joined while keeping the other dimensions aligned.

This example adds a row:

import numpy as np

matrix = np.array([[1, 2], [3, 4]])
with_row = np.append(matrix, [[5, 6]], axis=0)
print(with_row)

[[1 2]
 [3 4]
 [5 6]]

Every dimension except the one named by axis must match. For example, appending a row with three columns to a matrix with two columns is incompatible and raises ValueError:

import numpy as np

matrix = np.array([[1, 2], [3, 4]])
try:
    np.append(matrix, [[5, 6, 7]], axis=0)
except ValueError as error:
    print(type(error).__name__)

To add a column instead, pass a two-dimensional array with one row per existing row and one column of new values. Run this example:

import numpy as np

matrix = np.array([[1, 2], [3, 4]])
with_column = np.append(matrix, [[5], [6]], axis=1)
print(with_column)

[[1 2 5]
 [3 4 6]]

The result has the same two rows as matrix, with the new values in a third column. If the appended input has the wrong number of rows, check the dimensions before retrying.