# How does numpy.newaxis work and when to use it?

Simply put, `numpy.newaxis`

is used to * increase the dimension* of the existing array by

*one more dimension*, when used

*once*. Thus,

**1D**array will become**2D**array**2D**array will become**3D**array**3D**array will become**4D**array**4D**array will become**5D**array

and so on..

Here is a visual illustration which depicts *promotion* of 1D array to 2D arrays.

**Scenario-1**: `np.newaxis`

might come in handy when you want to *explicitly* convert a 1D array to either a *row vector* or a *column vector*, as depicted in the above picture.

**Example:**

`# 1D arrayIn [7]: arr = np.arange(4)In [8]: arr.shapeOut[8]: (4,)# make it as row vector by inserting an axis along first dimensionIn [9]: row_vec = arr[np.newaxis, :] # arr[None, :]In [10]: row_vec.shapeOut[10]: (1, 4)# make it as column vector by inserting an axis along second dimensionIn [11]: col_vec = arr[:, np.newaxis] # arr[:, None]In [12]: col_vec.shapeOut[12]: (4, 1)`

**Scenario-2**: When we want to make use of **numpy broadcasting** as part of some operation, for instance while doing *addition* of some arrays.

**Example:**

Let's say you want to add the following two arrays:

` x1 = np.array([1, 2, 3, 4, 5]) x2 = np.array([5, 4, 3])`

If you try to add these just like that, NumPy will raise the following `ValueError`

:

`ValueError: operands could not be broadcast together with shapes (5,) (3,)`

In this situation, you can use `np.newaxis`

to increase the dimension of one of the arrays so that NumPy can broadcast.

`In [2]: x1_new = x1[:, np.newaxis] # x1[:, None]# now, the shape of x1_new is (5, 1)# array([[1],# [2],# [3],# [4],# [5]])`

Now, add:

`In [3]: x1_new + x2Out[3]:array([[ 6, 5, 4], [ 7, 6, 5], [ 8, 7, 6], [ 9, 8, 7], [10, 9, 8]])`

Alternatively, you can also add new axis to the array `x2`

:

`In [6]: x2_new = x2[:, np.newaxis] # x2[:, None]In [7]: x2_new # shape is (3, 1)Out[7]: array([[5], [4], [3]])`

Now, add:

`In [8]: x1 + x2_newOut[8]: array([[ 6, 7, 8, 9, 10], [ 5, 6, 7, 8, 9], [ 4, 5, 6, 7, 8]])`

**Note**: Observe that we get the same result in both cases (but one being the transpose of the other).

**Scenario-3**: This is similar to scenario-1. But, you can use `np.newaxis`

more than once to *promote* the array to higher dimensions. Such an operation is sometimes needed for higher order arrays (*i.e. Tensors*).

**Example:**

`In [124]: arr = np.arange(5*5).reshape(5,5)In [125]: arr.shapeOut[125]: (5, 5)# promoting 2D array to a 5D arrayIn [126]: arr_5D = arr[np.newaxis, ..., np.newaxis, np.newaxis] # arr[None, ..., None, None]In [127]: arr_5D.shapeOut[127]: (1, 5, 5, 1, 1)`

As an alternative, you can use `numpy.expand_dims`

that has an intuitive `axis`

kwarg.

`# adding new axes at 1st, 4th, and last dimension of the resulting arrayIn [131]: newaxes = (0, 3, -1)In [132]: arr_5D = np.expand_dims(arr, axis=newaxes)In [133]: arr_5D.shapeOut[133]: (1, 5, 5, 1, 1)`

**More background on np.newaxis vs np.reshape**

`newaxis`

is also called as a pseudo-index that allows the temporary addition of an axis into a multiarray.

`np.newaxis`

uses the slicing operator to recreate the array while `numpy.reshape`

reshapes the array to the desired layout (assuming that the dimensions match; And this is * must* for a

`reshape`

to happen).**Example**

`In [13]: A = np.ones((3,4,5,6))In [14]: B = np.ones((4,6))In [15]: (A + B[:, np.newaxis, :]).shape # B[:, None, :]Out[15]: (3, 4, 5, 6)`

In the above example, we inserted a temporary axis between the first and second axes of `B`

(to use broadcasting). A missing axis is filled-in here using `np.newaxis`

to make the broadcasting operation work.

* General Tip*: You can also use

`None`

in place of `np.newaxis`

; These are in fact the same objects.`In [13]: np.newaxis is NoneOut[13]: True`

P.S. Also see this great answer: newaxis vs reshape to add dimensions

## What is `np.newaxis`

?

The `np.newaxis`

is just an alias for the Python constant `None`

, which means that wherever you use `np.newaxis`

you could also use `None`

:

`>>> np.newaxis is NoneTrue`

It's just more *descriptive* if you read code that uses `np.newaxis`

instead of `None`

.

## How to use `np.newaxis`

?

The `np.newaxis`

is generally used with slicing. It indicates that you want to add an additional dimension to the array. The position of the `np.newaxis`

represents where I want to add dimensions.

`>>> import numpy as np>>> a = np.arange(10)>>> aarray([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])>>> a.shape(10,)`

In the first example I use all elements from the first dimension and add a second dimension:

`>>> a[:, np.newaxis]array([[0], [1], [2], [3], [4], [5], [6], [7], [8], [9]])>>> a[:, np.newaxis].shape(10, 1)`

The second example adds a dimension as first dimension and then uses all elements from the first dimension of the original array as elements in the second dimension of the result array:

`>>> a[np.newaxis, :] # The output has 2 [] pairs!array([[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]])>>> a[np.newaxis, :].shape(1, 10)`

Similarly you can use multiple `np.newaxis`

to add multiple dimensions:

`>>> a[np.newaxis, :, np.newaxis] # note the 3 [] pairs in the outputarray([[[0], [1], [2], [3], [4], [5], [6], [7], [8], [9]]])>>> a[np.newaxis, :, np.newaxis].shape(1, 10, 1)`

## Are there alternatives to `np.newaxis`

?

There is another very similar functionality in NumPy: `np.expand_dims`

, which can also be used to insert one dimension:

`>>> np.expand_dims(a, 1) # like a[:, np.newaxis]>>> np.expand_dims(a, 0) # like a[np.newaxis, :]`

But given that it just inserts `1`

s in the `shape`

you could also `reshape`

the array to add these dimensions:

`>>> a.reshape(a.shape + (1,)) # like a[:, np.newaxis]>>> a.reshape((1,) + a.shape) # like a[np.newaxis, :]`

Most of the times `np.newaxis`

is the easiest way to add dimensions, but it's good to know the alternatives.

## When to use `np.newaxis`

?

In several contexts is adding dimensions useful:

If the data should have a specified number of dimensions. For example if you want to use

`matplotlib.pyplot.imshow`

to display a 1D array.If you want NumPy to broadcast arrays. By adding a dimension you could for example get the difference between all elements of one array:

`a - a[:, np.newaxis]`

. This works because NumPy operations broadcast starting with the last dimension^{1}.To add a necessary dimension so that NumPy

*can*broadcast arrays. This works because each length-1 dimension is simply broadcast to the length of the corresponding^{1}dimension of the other array.

^{1} If you want to read more about the broadcasting rules the NumPy documentation on that subject is very good. It also includes an example with `np.newaxis`

:

`>>> a = np.array([0.0, 10.0, 20.0, 30.0])>>> b = np.array([1.0, 2.0, 3.0])>>> a[:, np.newaxis] + barray([[ 1., 2., 3.], [ 11., 12., 13.], [ 21., 22., 23.], [ 31., 32., 33.]])`

You started with a one-dimensional list of numbers. Once you used `numpy.newaxis`

, you turned it into a two-dimensional matrix, consisting of four rows of one column each.

You could then use that matrix for matrix multiplication, or involve it in the construction of a larger 4 x n matrix.