NumPy Percentile: np.percentile Syntax and Methods

np.percentile returns the value below which a given percentage of the numbers in a NumPy array fall. You pass the array and one or more percentages between 0 and 100, for example np.percentile(a, [25, 50, 75]) for the quartiles. This page covers the signature, the method argument (which changes results on small samples), NaN handling, and how to report the numbers. Commands were checked against the NumPy 2.5 manual and every output shown was run on NumPy 2.5.1.

What np.percentile is used for in research

Researchers use it to summarise a distribution without assuming its shape: the median and interquartile range of skewed measurements, the 5th and 95th percentile of a simulation or bootstrap, or cut-offs for grouping participants into quartiles. For the concept itself, see percentile and quantile; for the single middle value, see median in NumPy. According to the NumPy manual, np.percentile(a, q) behaves like np.quantile(a, q/100), and the 50th percentile equals the median.

Install or access

NumPy’s installation page (numpy.org/install) gives pip install numpy and conda install numpy. Check the install with:

import numpy as np
print(np.__version__)

Step-by-step: compute percentiles

Signature

numpy.percentile(a, q, axis=None, out=None, overwrite_input=False,
                 method='linear', keepdims=False, *, weights=None)

• a: the array (or array-like) of data.
• q: a float or array of floats from 0 to 100 inclusive.
• axis: an int, a tuple of ints, or None. None flattens the array first.
• method: how to estimate a percentile between data points; default 'linear'. It was called interpolation before NumPy 1.22.0.
• keepdims: keeps the reduced axes as size-one dimensions so the result broadcasts against the input.
• weights: new in NumPy 2.0.0; only method='inverted_cdf' supports it.
• overwrite_input: if True, NumPy may modify the input array, and its contents are undefined afterwards.

Steps

1. Import NumPy and build the array: a = np.array([2, 4, 4, 5, 7, 9, 12, 15]).
2. Call the function with percentages on the 0 to 100 scale: np.percentile(a, [25, 50, 75]).
3. Read the result: array([4. , 6. , 9.75]).
4. For a 2-D array, choose the axis. With the NumPy manual’s example a = np.array([[10, 7, 4], [3, 2, 1]]): np.percentile(a, 50) gives 3.5, axis=0 gives [6.5, 4.5, 2.5], axis=1 gives [7., 2.], and axis=1, keepdims=True gives [[7.], [2.]].
5. For the interquartile range: q75, q25 = np.percentile(a, [75, 25]), then q75 - q25, which is 5.75 for the first sample.

Output and how to read it

With a single q and axis=None you get a scalar. With several values in q, the first axis of the result corresponds to q. Integer input, or floats narrower than float64, produce float64 output. In the first sample the 75th percentile, 9.75, is interpolated between the observed values 9 and 12; it is not itself an observation.

Choosing the method

On large samples the methods agree closely. On small samples they do not. The table shows the 90th percentile of the same eight values under every method listed in the NumPy manual, computed on NumPy 2.5.1. The manual describes inverted_cdf, averaged_inverted_cdf and closest_observation as discontinuous, and lower, higher, midpoint and nearest as discontinuous variants of linear.

method	np.percentile(a, 90)
inverted_cdf	15
averaged_inverted_cdf	15.0
closest_observation	12
interpolated_inverted_cdf	12.6
hazen	14.1
weibull	15.0
linear (default)	12.9
median_unbiased	14.5
normal_unbiased	14.4
lower	12
higher	15
midpoint	13.5
nearest	12

Values are rounded for display. The spread, from 12 to 15 on eight observations, is the reason to state the method in a methods section. When you cross-check against R, confirm the type argument of R’s quantile; see quantiles in R. For interpolation in general, see interpolation in NumPy.

Percentile scale versus quantile scale

np.percentile takes q from 0 to 100; np.quantile takes 0 to 1. Passing 0.5 to np.percentile asks for the 0.5th percentile, not the median.

Troubleshooting

ValueError: Percentiles must be in the range [0, 100]

Raised when any q is outside 0 to 100, for example np.percentile(a, 101). If you hold fractions such as 0.25, multiply by 100 or use np.quantile.

The result is nan

np.percentile propagates NaN: if the data contain any NaN, the result is nan. np.nanpercentile ignores NaN. With b = [2, 4, nan, 5, 7, 9, 12, 15], np.percentile(b, 50) returns nan and np.nanpercentile(b, 50) returns 7.0. The NumPy manual’s own example, [[10, nan, 4], [3, 2, 1]], gives nan and 3.0. Dropping missing values changes your sample, so report how many were excluded.

ValueError: Only method ‘inverted_cdf’ supports weights

Passing weights= with the default method raises this error (the message names the method you used). Add method='inverted_cdf'; weights need NumPy 2.0.0 or later.

The old interpolation argument

Code written for NumPy before 1.22.0 uses interpolation=; the argument is now method=.

Free alternatives

Tool	Call	Note
NumPy	np.quantile(a, 0.9)	Same estimator on a 0 to 1 scale; equal to np.percentile(a, 90) in the check above.
NumPy	np.nanpercentile(a, 50)	Ignores NaN.
Python standard library	statistics.quantiles(a, n=4, method='inclusive')	Returned [4.0, 6.0, 9.75] for the first sample, the same as NumPy’s default.
pandas	Series.quantile(q)	Takes q on the 0 to 1 scale.
R	quantile(x, probs)	See quantiles in R.

To see the quartiles graphically, see box plots in Matplotlib.

FAQ

What does np.percentile do?

It computes the q-th percentile of the data along a chosen axis, with q between 0 and 100, using the estimator set by method (default 'linear').

Is np.percentile the same as np.quantile?

Apart from the scale, yes: the NumPy manual states np.percentile(a, q) behaves like np.quantile(a, q/100).

How do I get the interquartile range?

Take the 75th and 25th percentiles in one call and subtract them, as in the steps above.

How do I ignore missing values?

Use np.nanpercentile; plain np.percentile returns nan if any value is NaN.

Which method should I report?

Report the NumPy version and the method value. The default is 'linear'; the table shows other methods can change small-sample results noticeably.

Sources

• NumPy manual (2.5), numpy.percentile, read 2026-11-08.
• NumPy manual, numpy.nanpercentile, read 2026-11-08.
• NumPy, Installing NumPy, read 2026-11-08.
• Outputs shown were computed with NumPy 2.5.1 on 2026-11-08.