Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
np.maximum(x1, x2) compares two arrays (or an array and a number) position by position and returns a new array holding the larger value at each position. It is NumPy’s element-wise maximum, a universal function (ufunc), and it is a different tool from np.max, which reduces one array to its largest value. This page is for researchers cleaning or transforming numeric data in Python who need to floor values, combine two arrays, or decide which “max” function fits.
What np.maximum is used for in research
The NumPy reference describes numpy.maximum as the “element-wise maximum of array elements”: it compares two arrays and returns a new array containing the element-wise maxima (NumPy v2.5 manual, read 2026-11-07). Typical research uses:
- Flooring a measurement at a reporting or detection limit, so no value falls below a chosen minimum.
- Taking the pointwise upper envelope of two curves, model outputs or replicate series that share a grid.
- Clamping one side only. For both a lower and an upper bound use np.clip.
Install or access
NumPy’s install page (numpy.org/install, read 2026-11-07) gives pip install numpy, or conda install numpy inside a conda environment. To isolate a project, create a virtual environment with python -m venv my-env and activate it with source my-env/bin/activate (macOS and Linux) or my-env\Scripts\activate (Windows). Then import it:
import numpy as npSyntax
numpy.maximum(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True)x1,x2: array_like. If their shapes differ they must be broadcastable to a common shape.- Returns an ndarray, or a scalar if both inputs are scalars.
out: optional array that receives the result.where: where True, the output is set to the ufunc result; elsewhere it keeps its original value.
Step-by-step: floor a column at a detection limit
- Import NumPy and load the values as an array.
- Choose the floor. Any scalar, or an array broadcastable to the data, works.
- Call
np.maximum(values, floor)and keep the returned array.
import numpy as np
values = np.array([0.2, 1.5, 0.05, 3.1])
np.maximum(values, 0.1)
# array([0.2, 1.5, 0.1, 3.1])The scalar 0.1 is broadcast against every element, so the third value (0.05) is replaced by 0.1 and the others are unchanged. Substituting a floor is a data-handling decision, not a neutral operation: record it in your analysis plan or methods text rather than letting it happen silently.
Two arrays and broadcasting
np.maximum([2, 3, 4], [1, 5, 2])
# array([2, 5, 4])
np.maximum(np.eye(2), [0.5, 2])
# array([[1. , 2. ],
# [0.5, 2. ]])In the second call, the length-2 list is broadcast across both rows of the 2×2 identity matrix. Both examples appear in the NumPy manual and were re-run locally on NumPy 2.5.1.
Output and how to read it
The result has the broadcast shape of the inputs and a dtype determined by NumPy’s type promotion. Each cell is whichever input was larger at that position. The manual notes that, when neither value is NaN, the result is equivalent to np.where(x1 >= x2, x1, x2), but faster and with proper broadcasting. See np.where for the conditional-selection form.
NaN handling
If one element in a comparison is NaN, np.maximum returns that NaN; if both are NaN, the first is returned. The manual’s summary is that NaNs are propagated. In a dataset with missing values, a single NaN therefore survives the operation:
n = np.array([1.0, np.nan, 3.0])
np.maximum(n, 2.0) # array([ 2., nan, 3.])
np.fmax(n, 2.0) # array([2., 2., 3.])np.fmax is the NaN-ignoring counterpart: it returns the non-NaN value when only one is NaN. Choose deliberately, because turning NaNs into numbers changes your data. See np.abs for another element-wise function.
out= and where=
With where, positions where the condition is False are left as in out. If you leave out=None, those positions are uninitialized in the returned array, so pass an explicit out when you use where:
np.maximum(values, 0.1, out=np.zeros(4), where=[True, False, True, True])
# array([0.2, 0. , 0.1, 3.1])Running maximum
As a ufunc, np.maximum also has the accumulate method, which gives a running maximum along a sequence: np.maximum.accumulate(np.array([1, 3, 2, 5, 4])) returns array([1, 3, 3, 5, 5]) (checked locally on NumPy 2.5.1).
np.maximum vs np.max vs np.fmax vs np.nanmax vs np.argmax
These are the functions people confuse. The “See also” entries of the np.maximum and np.max manual pages define the split:
| Function | What it does | NaN behaviour | Returns |
|---|---|---|---|
np.maximum(x1, x2) |
Element-wise maximum of two arrays | Propagates NaN | Array of the broadcast shape |
np.max(a, axis=None) |
Largest value in one array, or along an axis | Propagates NaN | A value, or an array reduced along the axis |
np.fmax(x1, x2) |
Element-wise maximum of two arrays | Ignores NaN | Array of the broadcast shape |
np.nanmax(a) |
Largest value along an axis | Ignores NaN | A value, or an array |
np.argmax(a) |
Position of the largest value | See the np.argmax guide | An index, not the value |
The np.max manual also warns not to use max for element-wise comparison of two arrays, and notes that when a.shape[0] is 2, maximum(a[0], a[1]) is faster than max(a, axis=0).
Troubleshooting
- Shapes cannot be broadcast. NumPy raises an error when the two shapes are incompatible. Reshape one input or add a trailing axis, for example
x[:, None]. - Output contains NaN where you expected a number. NaN propagation: use
np.fmax, or clean the NaNs first. - Odd values when using where=. Positions where the condition is False hold whatever
outheld; pass an initialisedout. - You wanted a single largest value. That is
np.max, notnp.maximum. - You need the cap and the floor. Use np.clip. For the smallest value see np.min;
np.minimumis the element-wise counterpart ofnp.maximum.
Free alternatives
| Tool | Same task |
|---|---|
Python built-in max() |
Largest item of an iterable or the larger of several arguments; not element-wise across arrays |
np.where(x1 >= x2, x1, x2) |
Equivalent when neither value is NaN, per the NumPy manual |
np.clip |
Floors and caps in one call |
FAQ
What does np.argmax mean?
np.argmax returns the index of the largest value, not the value itself. For a = [[3, 9, 2], [7, 1, 8]], np.argmax(a) is 1 (the position in the flattened array), and np.argmax(a, axis=1) is array([1, 2]). See np.argmax for the full treatment.
How do I check the maximum in an array?
Use np.max(a) for the overall maximum, np.max(a, axis=0) for each column and np.max(a, axis=1) for each row. For the example above these return 9, array([7, 9, 8]) and array([9, 8]). If the array contains NaN, np.max returns NaN; use np.nanmax to ignore it.
What is the function of max()?
Python’s built-in max() returns the largest item of an iterable, or the largest of several arguments. NumPy’s np.max does the same for arrays and adds axis, initial and where options. The NumPy manual shows that np.max([5], initial=6) returns 6 while max([5], default=6) returns 5: initial takes part in the comparison, while default applies only to an empty input.
How do I find the maximum element in Python?
max([3, 9, 2]) returns 9 for a plain list. For NumPy arrays, use np.max(a); to find where it sits, use np.argmax(a).
Sources
- NumPy documentation, numpy.maximum (v2.5), read 2026-11-07.
- NumPy documentation, numpy.max, read 2026-11-07.
- NumPy, Installing NumPy, read 2026-11-07.
