Median NumPy: np.median Syntax, axis, NaN and Output Type

The median numpy gives you comes from numpy.median, usually written np.median(a). It returns the middle value of the sorted data, and it returns the average of the two middle values when the count is even. Three behaviours catch people out and are covered below: a single NaN turns the whole result into NaN, integer input still returns a float, and the optional overwrite_input argument can leave your array partly sorted.

What numpy median is used for in research

The median is a resistant summary of centre: extreme values barely move it, which is why it is the usual choice for skewed measurements such as reaction times, costs or concentrations. See resistant measures for the general idea, why the mean exceeds the median in right-skewed data, and how to report the median with the interquartile range. The percentile view of the same quantity is in percentile and quantile.

In NumPy the definition is the one from the manual: take a sorted copy of the data; with N values, an odd N gives the value at position (N-1)/2, and an even N gives the average of the two middle values. Because of that averaging, the numpy median of an even-sized sample is often a number that does not appear in your data.

Install or access numpy median

Median numpy functions ship with NumPy itself, so there is nothing separate to install. The NumPy installation page (numpy.org/install, checked 2026-10-29) gives these commands:

• pip: pip install numpy, ideally inside a virtual environment created with python -m venv my-env
• conda: conda install numpy, from the defaults or conda-forge channel

Then import it in the usual way: import numpy as np.

Step by step: calculate a numpy median

The signature in the NumPy manual (v2.5, checked 2026-10-29) is:

numpy.median(a, axis=None, out=None, overwrite_input=False, keepdims=False)

1. Put the data in an array. The manual’s own example uses a = np.array([[10, 7, 4], [3, 2, 1]]).
2. Call it with no axis for one overall median. np.median(a) returns np.float64(3.5). With axis=None the median is taken over the flattened array.
3. Take the median down the columns with axis=0. np.median(a, axis=0) returns array([6.5, 4.5, 2.5]).
4. Take the median along each row with axis=1. np.median(a, axis=1) returns array([7., 2.]).
5. Pass a tuple of axes to flatten along several at once. np.median(a, axis=(0, 1)) returns np.float64(3.5), the same as the default for a two-dimensional array.
6. Keep the dimensions if you need to broadcast the result back. keepdims=True leaves the reduced axes in the result with size one.

Output and how to read a numpy median

Why np.median returns a float

For integer input, and for floats smaller than float64, np.median returns float64. Otherwise the result has the same dtype as the input. So the median of the integers 1, 3, 5 is reported as 3.0 rather than 3. Python’s standard-library statistics.median behaves differently: the Python documentation (docs.python.org, checked 2026-10-29) shows median([1, 3, 5]) giving 3 and median([1, 3, 5, 7]) giving 4.0. If you compare outputs from the two, expect the 3 versus 3.0 difference.

Even counts give an averaged value

For an even number of values both functions average the two middle values, so the result may not be a member of your data. When you need a value that is actually in the data set, the standard library offers statistics.median_low and statistics.median_high; for [1, 3, 5, 7] they return 3 and 5.

Does np.median change my array?

Not by default. With overwrite_input=True, NumPy may use the input array’s memory to save space, and the contents of the array are undefined afterwards (the manual says it will probably be partially sorted). If overwrite_input=True and a is not already an ndarray, an error is raised. Leave it at False unless memory is a real constraint and you no longer need the original ordering.

Troubleshooting numpy median

Does np.median ignore NaN?

No. The NumPy manual’s nanmedian page (checked 2026-10-29) shows it with the array [[10., 7, 4], [3, 2, 1]] after setting a[0, 1] = np.nan:

Call	Result
np.median(a)	np.float64(nan)
np.nanmedian(a)	3.0
np.nanmedian(a, axis=0)	array([6.5, 2. , 2.5])
np.median(a, axis=1)	array([nan, 2.])

The last row shows the damage is local to the slice: only the row containing the NaN becomes NaN. Use np.nanmedian when missing values should be ignored, and decide deliberately whether ignoring them is appropriate for your analysis before you report the number.

Empty data and sorting surprises in the standard library

If you switch to statistics.median, empty data raises StatisticsError, and the Python documentation advises removing NaN values beforehand because they can give surprising sort results.

The result has the wrong shape

Check the axis argument: the default None flattens everything into a single number. Use axis=0 or axis=1 for per-column or per-row medians, and keepdims=True if you need the reduced axis kept as length one.

Free alternatives to numpy median

Tool	Call	What the documentation says
NumPy	np.median(a)	Returns NaN if any value is NaN; float64 for integer input; axis and keepdims options.
NumPy	np.nanmedian(a)	Ignores NaN values.
Python standard library	statistics.median(data)	Mean of the middle two values for even counts; raises StatisticsError on empty data.
Python standard library	statistics.median_low(data), statistics.median_high(data)	Always return a member of the data set.
pandas	Series.median(skipna=True)	Signature Series.median(*, axis=0, skipna=True, numeric_only=False, **kwargs); NA values are excluded by default (pandas 3.1.0 documentation).

For a worked pandas workflow see Python for exploratory data analysis, and for a plot that displays the median and quartiles see the seaborn boxplot guide.

FAQ

Does np.median ignore NaN?

No. A single NaN makes np.median return NaN for the slice it falls in. Use np.nanmedian to skip NaN values.

Why does np.median return a float?

For integer input NumPy returns float64. The result for [1, 3, 5] is therefore 3.0.

Does np.median change my array?

Not unless you pass overwrite_input=True, in which case the array contents are undefined afterwards and are probably partially sorted.

What is the difference between numpy median and numpy.median?

They are the same thing: the function numpy.median, imported as np.median.

Sources

• NumPy manual, numpy.median (v2.5): https://numpy.org/doc/stable/reference/generated/numpy.median.html, checked 2026-10-29
• NumPy manual, numpy.nanmedian: https://numpy.org/doc/stable/reference/generated/numpy.nanmedian.html, checked 2026-10-29
• NumPy installation page: https://numpy.org/install/, checked 2026-10-29
• Python documentation, statistics module: https://docs.python.org/3/library/statistics.html, checked 2026-10-29
• pandas documentation, Series.median (3.1.0): https://pandas.pydata.org/docs/reference/api/pandas.Series.median.html, checked 2026-10-29