numpy.subtract() in Python

numpy.subtract() function is used when we want to compute the difference of two array.It returns the difference of arr1 and arr2, element-wise.

Syntax : numpy.subtract(arr1, arr2, /, out=None, *, where=True, casting=’same_kind’, order=’K’, dtype=None, subok=True[, signature, extobj], ufunc ‘subtract’)

Parameters :
arr1 : [array_like or scalar]1st Input array.
arr2 : [array_like or scalar]2nd Input array.
dtype : The type of the returned array. By default, the dtype of arr is used.
out : [ndarray, optional] A location into which the result is stored.
-> If provided, it must have a shape that the inputs broadcast to.
-> If not provided or None, a freshly-allocated array is returned.
where : [array_like, optional] Values of True indicate to calculate the ufunc at that position, values of False indicate to leave the value in the output alone.
**kwargs : Allows to pass keyword variable length of argument to a function. Used when we want to handle named argument in a function.

Return : [ndarray or scalar] The difference of arr1 and arr2, element-wise. Returns a scalar if both arr1 and arr2 are scalars.

Basic Example: Scalars and 1D Arrays

import numpy as np

# Scalar subtraction
a = 4
b = 6
print("a:", a)
print("b:", b)
print("np.subtract(a, b):", np.subtract(a, b))

# 1D array subtraction
arr1 = np.array([10, 20, 30])
arr2 = np.array([1, 2, 3])
result = np.subtract(arr1, arr2)
print("arr1:", arr1)
print("arr2:", arr2)
print("result:", result)

Output:

 a: 4 b: 6 np.subtract(a, b): -2 arr1: [10 20 30] arr2: [ 1 2 3] result: [ 9 18 27] 

Example: 2D Arrays and Broadcasting

import numpy as np

# 2x3 vs scalar
a = np.array([[5, 6, 7],
              [8, 9, 10]])
print("a:\n", a)

# subtract scalar
res1 = np.subtract(a, 3)
print("\na - 3:\n", res1)

# subtract array with compatible shape (1×3)
b = np.array([1, 2, 3])
res2 = np.subtract(a, b)
print("\na - b:\n", res2)

Output:

 a: [[ 5 6 7] [ 8 9 10]] a - 3: [[ 2 3 4] [ 5 6 7]] a - b: [[4 4 4] [7 7 7]] 

Note: Broadcasting allowed subtraction of a 1×3 array from a 2×3 array seamlessly.

Advanced Features: out, where, and dtype
Using out

import numpy as np

x = np.array([10, 20, 30, 40])
y = np.array([1, 2, 3, 4])
out = np.empty_like(x)
np.subtract(x, y, out=out)
print("out:", out)

Output:

 out: [ 9 18 27 36] 

Using where

import numpy as np

x = np.array([10, 20, 30, 40])
y = np.array([5, 25, 15, 35])
condition = x > y
result = np.subtract(x, y, where=condition, out=np.empty_like(x))
print("x:", x)
print("y:", y)
print("condition:", condition)
print("result:", result)

Output:

 x: [10 20 30 40] y: [ 5 25 15 35] condition: [ True False True True] result: [ 5 0 15 5] 

Specifying dtype

import numpy as np

x = np.array([14, 25, 46], dtype=np.int16)
y = np.array([7, 12, 23], dtype=np.int16)
res_float = np.subtract(x, y, dtype=np.float64)
res_int = np.subtract(x, y, dtype=np.int32)
print("res_float:", res_float, res_float.dtype)
print("res_int:",   res_int,   res_int.dtype)

Output:

 res_float: [ 7. 13. 23.] float64 res_int: [ 7 13 23] int32 

Common Use Cases

Time series differencing: np.subtract(series[1:], series[:-1]) to compute change between consecutive elements.

Image processing: Subtracting arrays of pixel values to adjust brightness, create negative images.

Data normalization: Subtracting mean value from array arr – arr.mean() (or np.subtract(arr, arr.mean())).

Memory-efficient in-place operations: Using out parameter to avoid extra allocation for large datasets.

Time complexity is O(n) where n is the number of elements processed.

Quick Overview

numpy.subtract() computes the element-wise difference of two arrays or an array and a scalar.

It supports broadcasting, optional output (out parameter), conditional subtraction via where, and specifying dtype.

Equivalent to the – operator for arrays, but provides extra control and parameters.

Ideal for data processing, scientific computing, image arithmetic, and any scenario where you need vectorised subtraction.