How to Use the Numpy Subtract Function

In this tutorial, I’ll explain how to use the Numpy subtract function – AKA np.subtract – to perform mathematical subtraction with Numpy arrays and other Python objects.

I’ll explain the syntax of np.subtract, how the function works, and how to use it.

If you need something specific, you can click on any of the following links.

Table of Contents:

Let’s start by quickly looking at what the function does.

A Quick Introduction to Numpy Subtract

As you might expect, the Numpy subtract function performs subtraction with Numpy arrays and other Python objects.

Perhaps the most important use of this function is to subtract the values of two same-sized Numpy arrays. When you use np.subtract on two same-sized Numpy arrays, the function will subtract the elements of the second array from the elements of the first array. It performs this subtraction in an “element-wise” fashion.

A simple visual example showing how Numpy subtract performs element-wise subtraction of the values of two same-sized input arrays.

Beyond using it for two same-sized arrays, you can also use Numpy subtract in a few other ways.

First, you can use np.subtract to operate on two scalar values. In this case, it will simply perform subtraction.

You can also use np.subtract on Python lists. When you do this, for the most part, np.subtract will treat the lists as Numpy arrays (and enforce the same rules with regard to size and shape that would apply to Numpy arrays). When you operate on lists, the output will be a Numpy array.

And finally, you can use the Numpy subtract function with a multi-dimensional array and a lower dimensional array. For example, you might use np.subtract on a 2-dimensional array and a 1-dimensional array. When you do this, Numpy will “broadcast” the lower dimensional array over slices of the higher dimensional array. Importantly, the arrays will need to be sized appropriately, such that broadcasting is possible (e.g., they need the same number of columns). Broadcasting may be confusing if you’re new to Numpy, so I’ll show you an example in the examples section.

Before we look at the examples though, let’s first look at the syntax.

The syntax of np.subtract

The syntax for the Numpy subtract function is simple:

An image that shows the syntax for the np.subtract function.

Note that the syntax shown above assumes that you’ve imported Numpy using the alias np.

Format of the input arrays

Although the syntax above is fairly simple, there are a few important things to keep in mind about the input arrays.

Data type of the inputs

First let’s talk about data type.

As you can see in the syntax explanation above, there are two inputs. Since this is Numpy that we’re talking about, these inputs are commonly Numpy arrays. The np.subtract is mostly designed to operate on arrays.

Having said that, np.subtract will also operate on other types of Python objects. Specifically, it will work with list-like objects, such as lists and tuples.

The “shape” of the inputs

Second, let’s talk about the shape of the input arrays. (This is important, because how the function operates depends on the shape of the two inputs.)

The first and most important way to use np.subtract is with two same-sized arrays. By this, I mean arrays with the same number of rows and columns. When you use Numpy subtract with two same-sized arrays, it will perform element-wise subtraction of the values of the input arrays.

An image that shows element-wise subtraction of two same-sized Numpy arrays.

In addition to operating on same-sized arrays, Numpy subtract will also operate on differently sized arrays. For example, you can operate on a 1-dimensional array and a 2-dimensional array. If you use np.subtract like this, then it will perform broadcasting. It will repeatedly subtract the smaller array from slices of the larger array. For this to work properly, the smaller array will need to have an appropriate shape, such that the number of elements matches the number of elements in the slices of the larger array.

Broadcasting is sometimes hard for beginners to grasp, so I’ll show you an example in example 4.

Additional parameters

In addition to the two input arrays, np.subtract a few optional parameters:

  • out
  • where

These are somewhat rarely used, but so I won’t explain them here.

Output of np.subtract

The output of np.subtract is a new Numpy array that contains the element-wise difference of the values of the input arrays.

Additionally, note that there is a special case for scalars: if both inputs to np.subtract are scalars, then the output will be a scalar.

Examples of how to subtract the values of Numpy arrays

Now that we’ve looked at the syntax, let’s look at a few examples of how to subtract values in Numpy arrays.


Preliminary code: Import Numpy and Create Arrays

Before you run the examples, you’ll need to run some code.

Specifically, you need to import Numpy and create some arrays that we can operate on.

Import Numpy

First, let’s just import Numpy.

You can import Numpy with this code:

import numpy as np

Create Arrays

Next, we’re going to create some Numpy arrays that we’ll be able to use with np.subtract.

Specifically, we’ll create:

  • a 1-dimensional ‘vector’ of numbers
  • a 2-dimensional ‘matrix’ of the numbers from 1 to 9 (ordered)
  • a 2-dimensional ‘matrix’ of the numbers from 1 to 9 (randomized)

We’ll use a few Numpy functions to make these.

We’ll use the np.array function to create a 1-dimensional vector of numeric values.

We’ll use np.arange to create an array that with a sequence of numbers from 1 to 9. This will be called numbers_1_to_9. To be clear, we won’t use this array directly. We’ll only use it to create some other arrays.

From numbers_1_to_9, we’ll create two additional arrays: matrix_2d_ordered and matrix_2d_random. These will be the numbers from 1 to 9, arranged in order in a 3 by 3 matrix, and the numbers from 1 to 9, arranged randomly in a 3 by 3 matrix.

vector_1d = np.array([3,4,5])

numbers_1_to_9 = np.arange(start = 1, stop = 10)
matrix_2d_ordered = numbers_1_to_9.reshape((3,3))

matrix_2d_random = np.random.choice(size = (3,3), a = numbers_1_to_9, replace = False)

If what we’re doing here confuses you, then you should click on the links I just referenced in the read the tutorials I linked to in the previous couple of paragraphs. Those tutorials explain the techniques we’ve used to create these arrays.

After you run the code to create the arrays, you’ll be ready to run the examples.

EXAMPLE 1: Use Numpy to subtract one scalar from another

Let’s start with a very simple example.

Here, we’ll use the Numpy subtract function to subtract one scalar value from another.





This is a very simple example

Here, we’re subtracting the value 4 from the value 12. The result is 8.

EXAMPLE 2: Subtract a scalar from an array

Next, let’s subtract a scalar value from an array.

Specifically, we’ll subtract the value 3 from matrix_2d_ordered.

np.subtract(matrix_2d_ordered, 3)


array([[-2, -1,  0],
       [ 1,  2,  3],
       [ 4,  5,  6]])


Here, we’ve used np.subtract with a scalar and a Numpy array.

For the output, np.subtract has subtracted 3 from every element of the array matrix_2d_ordered.

The output is a new array, with the new elements.

Also, note that the output is the same shape as the input array, matrix_2d_ordered.

EXAMPLE 3: Subtract two same-sized Numpy arrays

In this example, let’s operate on two same-sized arrays.

Specifically, we’ll subtract matrix_2d_random from matrix_2d_ordered.

np.subtract(matrix_2d_ordered, matrix_2d_random)


array([[-8,  0, -1],
       [ 1, -2,  5],
       [-1,  3,  3]])


In this example, the np.subtract function is subtracting the values of matrix_2d_random from the corresponding values of matrix_2d_ordered, in an element-wise way.

An image showing np.subtract performing subtraction on two same-sized Numpy arrays, in an element-wise fashion.

Also, take a look at the shape of the output. The output array is the same shape as the input arrays. This is how np.subtract works when we use two same-sized inputs.

EXAMPLE 4: Subtract a vector from a matrix (i.e., broadcasting)

Finally, let’s operate on a 1D array and a 2D array.

Specifically, we’ll use np.subtract to subtract the 1D array, vector_1d, from each row of the 2D array, matrix_2d_ordered.

np.subtract(matrix_2d_ordered, vector_1d)


array([[-4, -2,  0],
       [-1,  1,  3],
       [ 2,  4,  6]])


In this example, we’ve subtracted the 1D array vector_1d from the 2D array matrix_2d_ordered.

Notice how both the 1D array and the 2D array have the same number of columns. This allows Numpy to subtract the elements of vector_1d from each row of matrix_2d_ordered.

In Numpy, we call this “broadcasting.” Here, np.subtract is “broadcasting” the 1-dimensional array across the rows of the 2-dimensional array.

So here, np.subtract is subtracting the values of vector_1d from row 1 of matrix_2d_ordered, element wise. Then it subtracts the values of vector_1d to row 2 of matrix_2d_ordered. And so on.

An image that shows how Numpy subtracts the values of a 1D array from the rows of a 2D array, which we call 'broadcasting'.

Here, I’ll reemphasize that this is possible because the number of elements in vector_1d is the same as the number of columns in matrix_2d_ordered. In order for broadcasting to work properly, the the number of columns in both input arrays need to be appropriately sized.

Leave your other questions in the comments below

Do you have other questions about how to use np.subtract to perform subtraction in Numpy?

If so, leave your questions in the comments section below.

Join our course to learn more about Numpy

In this tutorial, I’ve explained how to subtract Numpy arrays with np.subtract.

This should help you with performing matrix subtraction, but if you really want to learn Numpy, there’s a lot more to learn.

If you’re serious about mastering Numpy, and serious about data science in Python, you should consider joining our premium course called Numpy Mastery.

Numpy Mastery will teach you everything you need to know about Numpy, including:

  • How to create Numpy arrays
  • How to reshape, split, and combine your Numpy arrays
  • What the “Numpy random seed” function does
  • How to use the Numpy random functions
  • How to perform mathematical operations on Numpy arrays
  • and more …

Moreover, this course will show you a practice system that will help you master the syntax within a few weeks. We’ll show you a practice system that will enable you to memorize all of the Numpy syntax you learn. If you have trouble remembering Numpy syntax, this is the course you’ve been looking for.

Find out more here:

Learn More About Numpy Mastery

Joshua Ebner

Joshua Ebner is the founder, CEO, and Chief Data Scientist of Sharp Sight.   Prior to founding the company, Josh worked as a Data Scientist at Apple.   He has a degree in Physics from Cornell University.   For more daily data science advice, follow Josh on LinkedIn.

Leave a Comment