Introduction

In NumPy, percentiles are calculated with numpy.percentile, which returns the value below which a chosen percentage of the data falls. The function is simple to use for one-dimensional arrays, but it also supports multiple percentiles, axis-aware calculations, and different estimation methods.

The Basic Call

For a one-dimensional array, the syntax is straightforward:

1import numpy as np
2
3values = np.array([10, 20, 30, 40, 50])
4
5p50 = np.percentile(values, 50)
6p90 = np.percentile(values, 90)
7
8print("50th percentile:", p50)
9print("90th percentile:", p90)

This calculates:

• the median when q=50
• the 90th percentile when q=90

The percentile argument must be in the range from 0 to 100.

Request Several Percentiles at Once

NumPy can return multiple percentiles in one call:

1import numpy as np
2
3values = np.array([3, 7, 8, 12, 15, 21, 30])
4result = np.percentile(values, [25, 50, 75])
5
6print(result)

This is useful when you want quartiles or a standard summary of distribution spread.

Common interpretations:

• 25th percentile is the first quartile
• 50th percentile is the median
• 75th percentile is the third quartile

Calculate Percentiles Along an Axis

For multidimensional arrays, use the axis parameter to control the direction of the calculation.

1import numpy as np
2
3data = np.array([
4    [10, 20, 30],
5    [40, 50, 60],
6    [70, 80, 90],
7])
8
9print(np.percentile(data, 50, axis=0))
10print(np.percentile(data, 50, axis=1))

Here:

• 'axis=0 computes percentiles column by column'
• 'axis=1 computes percentiles row by row'

If you omit axis, NumPy flattens the array first.

Be Aware of the Estimation Method

Percentiles are not always defined identically across tools, especially for small datasets. NumPy exposes this through the method parameter.

1import numpy as np
2
3values = np.array([1, 2, 3, 4])
4
5print(np.percentile(values, 25, method="linear"))
6print(np.percentile(values, 25, method="nearest"))
7print(np.percentile(values, 25, method="midpoint"))

Different methods can produce different answers on the same data. That matters when:

• you need to match another system
• you are comparing results against Excel, R, or a database
• the dataset is small and interpolation choices matter

In modern NumPy, the argument is named method. Older code and older documentation may still mention interpolation, which has been replaced.

Handling Missing Values

If your array contains NaN values, regular percentile will propagate them. Use nanpercentile when you want to ignore missing entries.

1import numpy as np
2
3values = np.array([10, 20, np.nan, 40, 50])
4
5print(np.percentile(values, 50))
6print(np.nanpercentile(values, 50))

This is a common source of confusion in data analysis workflows where missing values are normal.

Percentiles and Quantiles Are Closely Related

NumPy also provides quantile, which is the same idea expressed on a 0 to 1 scale instead of 0 to 100.

1import numpy as np
2
3values = np.array([10, 20, 30, 40, 50])
4
5print(np.percentile(values, 75))
6print(np.quantile(values, 0.75))

These two calls refer to the same location in the distribution.

Keep the Use Case in Mind

Percentiles are especially useful for:

• latency distributions
• income or salary summaries
• exam score cutoffs
• monitoring systems where the median and tail matter more than the mean

For example, the 95th percentile of request latency is often more informative than the average because it captures slow-tail behavior directly.

Common Pitfalls

• Passing percentile values on a 0 to 1 scale to np.percentile, which expects 0 to 100.
• Forgetting about the axis argument and accidentally computing percentiles over the flattened array.
• Comparing results with another tool without matching the percentile estimation method.
• Using np.percentile on arrays with NaN values when np.nanpercentile is the intended function.
• Treating percentiles as unique universal values even though small-sample interpolation choices can differ across implementations.

Summary

• Use np.percentile(data, q) to compute the qth percentile of an array.
• Pass a list of percentile values when you want several results in one call.
• Use axis to control whether the calculation happens across rows, columns, or the flattened array.
• Use method when you need to control how NumPy estimates percentiles.
• Use np.nanpercentile if missing values should be ignored rather than propagated.