NumPy: append() to add values to an array
In NumPy, the np.append() function allows you to add values (elements, rows, or columns) to either the end or the beginning of an array (ndarray).
Note that append() is not provided as a method of ndarray.
See the following article on how to concatenate multiple arrays.
Use np.insert() to insert values at any position, not just at the end or beginning.
The NumPy version used in this article is as follows. Note that functionality may vary between versions.
import numpy as np
print(np.__version__)
# 1.26.1
Basic usage of np.append()
Add elements to the end
To demonstrate the basic usage of np.append(), use a one-dimensional array as an example.
Specify the original array as the first argument and the value to add as the second. The function returns a new array, leaving the original one unchanged.
a = np.arange(3)
print(a)
# [0 1 2]
a_append = np.append(a, 3)
print(a_append)
# [0 1 2 3]
print(a)
# [0 1 2]
Both the first and second arguments can be any array-like object, such as a list or ndarray. The return value is always an ndarray.
print(np.append(a, [3, 4, 5]))
# [0 1 2 3 4 5]
print(np.append(a, np.arange(3, 6)))
# [0 1 2 3 4 5]
Add elements to the beginning
To add values to the beginning instead of the end, swap the first and second argument objects.
a = np.arange(3)
print(a)
# [0 1 2]
print(np.append(-1, a))
# [-1 0 1 2]
print(np.append([-3, -2, -1], a))
# [-3 -2 -1 0 1 2]
print(np.append(np.arange(-3, 0), a))
# [-3 -2 -1 0 1 2]
np.append() with two-dimensional arrays
Add rows/columns by specifying the axis argument
By default, when the first argument is a two-dimensional array, it is flattened to one dimension, and then the values from the second argument are appended to it.
a_2d = np.arange(6).reshape(2, 3)
print(a_2d)
# [[0 1 2]
# [3 4 5]]
print(np.append(a_2d, 10))
# [ 0 1 2 3 4 5 10]
Similarly, if the second argument is an array, it is also flattened. The first and second arguments are then concatenated into a single one-dimensional array.
a_2d_ex = np.arange(6).reshape(2, 3) * 10
print(a_2d_ex)
# [[ 0 10 20]
# [30 40 50]]
print(np.append(a_2d, a_2d_ex))
# [ 0 1 2 3 4 5 0 10 20 30 40 50]
To add arrays while preserving dimensions, specify the axis argument. Use axis=0 to add a new row (vertical concatenation) and axis=1 to add a new column (horizontal concatenation). Specifying a non-existent dimension results in an error.
print(np.append(a_2d, a_2d_ex, axis=0))
# [[ 0 1 2]
# [ 3 4 5]
# [ 0 10 20]
# [30 40 50]]
print(np.append(a_2d, a_2d_ex, axis=1))
# [[ 0 1 2 0 10 20]
# [ 3 4 5 30 40 50]]
# print(np.append(a_2d, a_2d_ex, axis=2))
# AxisError: axis 2 is out of bounds for array of dimension 2
When adding a new row with axis=0, the number of columns must match the original array, and when adding a new column with axis=1, the number of rows must match. Note that missing parts are not filled with NaN values.
a_2d_ex2 = np.arange(2).reshape(1, 2) * 10
print(a_2d_ex2)
# [[ 0 10]]
# print(np.append(a_2d, a_2d_ex2, axis=0))
# ValueError: all the input array dimensions except for the concatenation axis must match exactly, but along dimension 1, the array at index 0 has size 3 and the array at index 1 has size 2
# print(np.append(a_2d, a_2d_ex2, axis=1))
# ValueError: all the input array dimensions except for the concatenation axis must match exactly, but along dimension 0, the array at index 0 has size 2 and the array at index 1 has size 1
As with the one-dimensional example, swapping the first and second arguments reverses the order.
print(np.append(a_2d_ex, a_2d, axis=0))
# [[ 0 10 20]
# [30 40 50]
# [ 0 1 2]
# [ 3 4 5]]
print(np.append(a_2d_ex, a_2d, axis=1))
# [[ 0 10 20 0 1 2]
# [30 40 50 3 4 5]]
It is also possible to specify a two-dimensional list (list of lists) instead of an ndarray.
print(np.append(a_2d, [[0, 10, 20], [30, 40, 50]], axis=0))
# [[ 0 1 2]
# [ 3 4 5]
# [ 0 10 20]
# [30 40 50]]
Differences from np.vstack() and np.hstack()
In np.append(), mismatched dimensions between specified arrays trigger an error.
For example, to add a single row to a two-dimensional array, both arrays must be two-dimensional. Use reshape() to adjust the shape.
a_2d = np.arange(6).reshape(2, 3)
print(a_2d)
# [[0 1 2]
# [3 4 5]]
a_row_1d = np.arange(3) * 10
print(a_row_1d)
# [ 0 10 20]
# print(np.append(a_2d, a_row_1d, axis=0))
# ValueError: all the input arrays must have same number of dimensions, but the array at index 0 has 2 dimension(s) and the array at index 1 has 1 dimension(s)
print(a_row_1d.reshape(1, 3))
# [[ 0 10 20]]
print(np.append(a_2d, a_row_1d.reshape(1, 3), axis=0))
# [[ 0 1 2]
# [ 3 4 5]
# [ 0 10 20]]
The same applies to columns.
a_col_1d = np.arange(2) * 10
print(a_col_1d)
# [ 0 10]
# print(np.append(a_2d, a_col_1d, axis=1))
# ValueError: all the input arrays must have same number of dimensions, but the array at index 0 has 2 dimension(s) and the array at index 1 has 1 dimension(s)
print(a_col_1d.reshape(2, 1))
# [[ 0]
# [10]]
print(np.append(a_2d, a_col_1d.reshape(2, 1), axis=1))
# [[ 0 1 2 0]
# [ 3 4 5 10]]
np.vstack(), which concatenates arrays vertically, can concatenate a two-dimensional array and a one-dimensional array directly. You can specify multiple arrays to concatenate at once in a list.
print(np.vstack([a_2d, a_row_1d]))
# [[ 0 1 2]
# [ 3 4 5]
# [ 0 10 20]]
print(np.vstack([a_2d, a_row_1d, [[0, -1, -2], [-3, -4, -5]]]))
# [[ 0 1 2]
# [ 3 4 5]
# [ 0 10 20]
# [ 0 -1 -2]
# [-3 -4 -5]]
np.hstack(), which concatenates arrays horizontally, requires matching dimensions like np.append(), but it can concatenate multiple arrays at once.
# print(np.hstack([a_2d, a_col_1d]))
# ValueError: all the input arrays must have same number of dimensions, but the array at index 0 has 2 dimension(s) and the array at index 1 has 1 dimension(s)
print(np.hstack([a_2d, a_col_1d.reshape(2, 1), [[0, -1], [-2, -3]]]))
# [[ 0 1 2 0 0 -1]
# [ 3 4 5 10 -2 -3]]
While it may be a matter of personal preference, using np.vstack() or np.hstack() can be more intuitive for concatenating two-dimensional arrays.
Additionally, there is np.dstack() for concatenating two-dimensional arrays depth-wise to create a three-dimensional array. For more details, see the article below.
np.append() with three-dimensional and higher-dimensional arrays
The approach for three-dimensional and higher-dimensional arrays follows the same principle.
By default (axis=None), the array is flattened to one dimension before being added to the end.
a_3d = np.arange(12).reshape(2, 3, 2)
print(a_3d)
# [[[ 0 1]
# [ 2 3]
# [ 4 5]]
#
# [[ 6 7]
# [ 8 9]
# [10 11]]]
print(np.append(a_3d, 100))
# [ 0 1 2 3 4 5 6 7 8 9 10 11 100]
When the axis argument is specified, the arrays are concatenated along the respective axes.
For three-dimensional and higher-dimensional arrays, it might be hard to imagine how they're concatenated just by looking at the output, so it is good to check the shape to get a better understanding.
a_3d_ex = np.arange(12).reshape(2, 3, 2) * 10
print(a_3d_ex)
# [[[ 0 10]
# [ 20 30]
# [ 40 50]]
#
# [[ 60 70]
# [ 80 90]
# [100 110]]]
print(a_3d_ex.shape)
# (2, 3, 2)
print(np.append(a_3d, a_3d_ex, axis=0))
# [[[ 0 1]
# [ 2 3]
# [ 4 5]]
#
# [[ 6 7]
# [ 8 9]
# [ 10 11]]
#
# [[ 0 10]
# [ 20 30]
# [ 40 50]]
#
# [[ 60 70]
# [ 80 90]
# [100 110]]]
print(np.append(a_3d, a_3d_ex, axis=0).shape)
# (4, 3, 2)
print(np.append(a_3d, a_3d_ex, axis=1))
# [[[ 0 1]
# [ 2 3]
# [ 4 5]
# [ 0 10]
# [ 20 30]
# [ 40 50]]
#
# [[ 6 7]
# [ 8 9]
# [ 10 11]
# [ 60 70]
# [ 80 90]
# [100 110]]]
print(np.append(a_3d, a_3d_ex, axis=1).shape)
# (2, 6, 2)
print(np.append(a_3d, a_3d_ex, axis=2))
# [[[ 0 1 0 10]
# [ 2 3 20 30]
# [ 4 5 40 50]]
#
# [[ 6 7 60 70]
# [ 8 9 80 90]
# [ 10 11 100 110]]]
print(np.append(a_3d, a_3d_ex, axis=2).shape)
# (2, 3, 4)
np.concatenate() is useful for sequentially concatenating multiple arrays.
print(np.concatenate([a_3d_ex, a_3d, a_3d_ex], axis=2))
# [[[ 0 10 0 1 0 10]
# [ 20 30 2 3 20 30]
# [ 40 50 4 5 40 50]]
#
# [[ 60 70 6 7 60 70]
# [ 80 90 8 9 80 90]
# [100 110 10 11 100 110]]]
For more details, refer to the following article.