SciPy · Function

ndimage.median_filter

Calculates a multidimensional median filter over an input array. The neighborhood can be rectangular via size or selectively defined with a boolean footprint, with configurable boundaries and output handling.

How it works

The function visits each position in the input and computes a median from the neighborhood selected by size or footprint. It can process selected axes, extend values beyond boundaries according to mode, shift the neighborhood with origin, and return results in a supplied output array or dtype.

Syntax

scipy.ndimage.median_filter(input, size=None, footprint=None, output=None, mode='reflect', cval=0.0, origin=0, *, axes=None)

Parameters

Name	Type	Description
`input`	`array_like`	Input array.
`size`	`scalar or tuple, optional`	Neighborhood shape; see footprint.
`footprint`	`array, optional`	Boolean neighborhood mask; either size or footprint must be defined.
`output`	`array or dtype, optional`	Array receiving the result, or dtype for the returned array.
`mode`	`{'reflect', 'constant', 'nearest', 'mirror', 'wrap'}, optional`	Boundary extension mode: 'reflect', 'constant', 'nearest', 'mirror', or 'wrap'.
`cval`	`scalar, optional`	Constant used with constant boundary extension.
`origin`	`int or sequence, optional`	Filter placement offset; zero centers the filter, positive shifts left, and negative shifts right.
`axes`	`tuple of int, optional`	Axes over which to apply the filter.

Returns

median_filter ndarray: filtered array with the same shape as input.

Key points

Use median_filter to replace each location with the median of its selected multidimensional neighborhood.
size describes the neighborhood shape applied at every position.
footprint lets you choose which positions within an implicit neighborhood contribute to the median.
mode selects boundary extension behavior for neighborhoods reaching outside the input.
Without an output specification, the result is newly allocated with the input dtype.
The filtered array preserves the input shape.

Common mistakes

Provide at least one of size or footprint; a call that omits both does not specify the filtering neighborhood.
Do not expect size to affect the result when footprint is supplied.
Nonzero origin values shift the neighborhood, so verify alignment when using origin.
output accepts either storage for results or a dtype, so distinguish an output array from a type specification.

Example: Denoise a 2D array

import numpy as np
from scipy import ndimage

image = np.array([[1, 2, 100],
                  [3, 4, 5],
                  [6, 7, 8]])
filtered = ndimage.median_filter(image, size=3)
print(filtered)

Applies a 3-by-3 median filter to a two-dimensional array, using the default boundary handling.

When to use it

Impulse-noise reduction

Removing isolated spikes from grayscale image or sensor data while preserving sharp transitions.

Multidimensional smoothing

Applying a neighborhood median over arrays with one or more dimensions.

Custom neighborhood filtering

Selecting a cross-shaped or otherwise sparse neighborhood instead of a full rectangular window.

Interview questions

QWhat does scipy.ndimage.median_filter do?

It computes a multidimensional median filter: each output element is the median of input values selected by a size-shaped neighborhood or a boolean footprint. The returned array has the same shape as the input.

Follow-up: How can boundary behavior be controlled? Use mode to choose the extension rule and cval as the constant value when mode='constant'.

QHow do size and footprint differ?

size defines the neighborhood shape, while footprint is a boolean array that specifies both an implicit shape and which positions participate. If footprint is provided, size is ignored.

Follow-up: When would footprint be preferable? Use it for sparse or non-rectangular neighborhoods, such as a cross-shaped mask.

QHow are edges and alignment handled?

mode controls how the input is extended outside its boundaries; supported choices are reflect, constant, nearest, mirror, and wrap. origin controls neighborhood placement, with zero centering it and positive or negative values shifting it.

Follow-up: How can filtering be restricted to selected dimensions? Supply axes, and coordinate its size, footprint, and origin values with those axes.

scipy.ndimage.rank_filter
scipy.ndimage.percentile_filter
scipy.ndimage.generic_filter
scipy.ndimage.maximum_filter
scipy.ndimage.minimum_filter

Source: median_filter — SciPy v1.18.0 Manual. Checked 2026-10-15.