Written and maintained by CASRAI Editorial Board
Last updated
numpy.append(arr, values, axis=None) returns a new array: a copy of arr with values added at the end. It does not change arr, and without an axis it flattens everything into a one-dimensional result. Those three facts explain nearly every surprise people hit when they search for “numpy append”.
This guide follows the NumPy v2.5 manual, checked 2026-10-29. It covers the shape rules for axis, the exact error you get when shapes do not line up, a dtype trap, and why numpy ndarray append and numpy.ndarray append searches lead to a function rather than a method.
What np.append is used for in research code
Analysis scripts often need to add a row, a column or a few values to an existing array: a new measurement to a series, a row to a results matrix. np.append does this by allocating and filling a new array. The manual states: “Note that append does not occur in-place: a new array is allocated and filled.” You must therefore assign the return value, for example result = np.append(result, new_values).
Install or access
NumPy’s own install page (numpy.org/install) lists two routes. With pip: pip install numpy. With conda: create and activate an environment (conda create -n my-env, then conda activate my-env), then run conda install numpy. Then import it and check the version:
import numpy as np
print(np.__version__)Step by step: np.append with and without axis
Syntax and parameters
The signature is numpy.append(arr, values, axis=None). arr holds the array that values are appended to a copy of. values must be of the correct shape: “the same shape as arr, excluding axis”. If axis is not specified, “values can be any shape and will be flattened before use”.
- Import NumPy.
import numpy as np - Append without an axis (flattened result).
np.append([1, 2, 3], [[4, 5, 6], [7, 8, 9]])returnsarray([1, 2, 3, 4, 5, 6, 7, 8, 9]). Both inputs are flattened before use, so the result is one-dimensional even though the second input was two-dimensional. - Append rows with axis=0.
np.append([[1, 2, 3], [4, 5, 6]], [[7, 8, 9]], axis=0)returns a 3×3 array: the original two rows followed by[7, 8, 9]. The array keeps its two dimensions becauseaxiswas given. - Append along axis=1. The same rule applies:
valuesmust have the same shape asarrin every dimension except the one named byaxis, so foraxis=1the two arrays need the same number of rows. - Assign the result. Because the original is untouched, store the return value in a variable.
Shape rules at a glance
| Call | What happens to the inputs | Result |
|---|---|---|
np.append(a, b) (axis=None) |
Both arr and values are flattened before use |
One-dimensional copy |
np.append(a, b, axis=0) |
values must match arr in every dimension except axis 0 |
Copy with the new items added along axis 0 |
np.append(a, b, axis=1) |
values must match arr in every dimension except axis 1 |
Copy with the new items added along axis 1 |
Output and how to read it
- It is a copy. The manual describes the return value as “A copy of arr with values appended to axis.”
- Flattening changes dimensionality. If you pass no
axis, a two-dimensional input comes back one-dimensional. If you expected a matrix, addaxis. - Check the dtype. In the manual’s example,
a = np.array([1, 2], dtype=np.int_)followed byc = np.append(a, [])givesarray([1., 2.])with dtypefloat64, because an empty list defaults to float64. Appending even an empty list can therefore turn an integer array into a float array.
Troubleshooting
ValueError: all the input arrays must have same number of dimensions
The manual’s own example triggers it: np.append([[1, 2, 3], [4, 5, 6]], [7, 8, 9], axis=0) raises “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)”. With an explicit axis, a two-dimensional arr needs a two-dimensional values. Write [[7, 8, 9]] instead of [7, 8, 9], or drop axis if you want a flattened result.
My integer array became floats
See the dtype example above. The empty-list default is float64, so check .dtype after appending.
AttributeError when calling arr.append(x)
See the next section: append is not a method of ndarray.
numpy ndarray append and numpy.ndarray append
Searches for numpy ndarray append and numpy.ndarray append usually mean “add an element to an array”. The numpy.ndarray reference page in the manual lists no append method, so arr.append(x) is not valid on an ndarray. Use the module function np.append(arr, x) or np.concatenate. The same ndarray page lists ndarray.resize, described as “Change shape and size of array in-place”, which is a different operation from appending.
Free alternatives: np.append compared with np.concatenate
Both NumPy functions are free and ship with NumPy. The table compares the two manual pages.
| Feature | np.append | np.concatenate |
|---|---|---|
| Signature | numpy.append(arr, values, axis=None) |
numpy.concatenate(arrays, /, axis=0, out=None, *, dtype=None, casting='same_kind') |
| What it takes | An array and the values to add | A sequence of arrays |
| Default axis | None: inputs are flattened |
0: joins along the first axis; axis=None flattens |
| Shape rule | Same shape as arr, excluding axis |
Same shape, except in the dimension corresponding to axis |
| In-place? | No: a new array is allocated and filled | Returns the joined array; an out parameter is available |
The concatenate manual also lists the alias numpy.concat, added in NumPy 2.0. Its examples include np.concatenate((a, b), axis=0) with a = [[1, 2], [3, 4]] and b = [[5, 6]], giving [[1, 2], [3, 4], [5, 6]], and np.concatenate((a, b.T), axis=1) giving [[1, 2, 5], [3, 4, 6]].
FAQ
Does np.append change the original array?
No. It returns a copy with the values appended; a new array is allocated and filled.
Why is my result one-dimensional?
When axis is not given, both arr and values are flattened before use. Pass axis=0 or axis=1 to keep the dimensions.
How do I append a row to a two-dimensional array?
Use np.append(arr, [[7, 8, 9]], axis=0), with the new row as a two-dimensional list, as in the manual’s example.
What is numpy ndarray append?
There is no append method on numpy.ndarray; use np.append or np.concatenate.
Related CASRAI guides
More NumPy function guides: NumPy unique, NumPy repeat and axis, NumPy where and NumPy NaN handling. For array basics see NumPy arrays.
Sources
- NumPy v2.5 Manual, numpy.append, checked 2026-10-29.
- NumPy v2.5 Manual, numpy.concatenate, checked 2026-10-29.
- NumPy, Installing NumPy, checked 2026-10-29.
- NumPy v2.5 Manual, numpy.ndarray, checked 2026-10-29.
