SciPy · Function

stats.wilcoxon

Performs the Wilcoxon signed-rank test for paired measurements or supplied paired differences. It returns a signed-rank statistic and p-value for the selected alternative hypothesis and calculation method.

How it works

The function compares paired observations through their differences and applies the Wilcoxon signed-rank test. It can accept two paired samples or a single array of precomputed differences, then returns a statistic and p-value; options control zero differences, the alternative hypothesis, p-value method, axis handling, missing values, and output dimensions.

Syntax

scipy.stats.wilcoxon(x, y=None, zero_method='wilcox', correction=False, alternative='two-sided', method='auto', *, axis=0, nan_policy='propagate', keepdims=False)

Parameters

Name	Type	Description
`x`	`array_like`	First measurement set, or the paired differences when `y` is omitted.
`y`	`array_like or None`	Second measurement set paired elementwise with `x`; omit it when `x` contains differences.
`zero_method`	`{'wilcox', 'pratt', 'zsplit'}`	Treatment of zero differences; default is `wilcox`.
`correction`	`bool`	Whether to apply continuity correction; default is `False`.
`alternative`	`{'two-sided', 'greater', 'less'}`	Alternative hypothesis: `two-sided`, `greater`, or `less`; default is `two-sided`.
`method`	`{'auto', 'exact', 'asymptotic'} or PermutationMethod`	Method used to calculate the p-value; default is `auto`.
`axis`	`int or None`	Axis along which to perform the test; default is `0`.
`nan_policy`	`{'propagate', 'omit', 'raise'}`	How to handle NaNs: `propagate`, `omit`, or `raise`; default is `propagate`.
`keepdims`	`bool`	Whether reduced axes are retained in the output; default is `False`.

Returns

A result containing statistic and pvalue; each may be scalar or array-like depending on the input and axis.

Key points

Use this function for paired, non-parametric comparisons rather than an independent-samples test.
The test is designed for measurements that form meaningful pairs, such as before-and-after observations.
The central calculation is based on signed ranks of paired differences relative to zero.
x can contain the first paired measurement set when y supplies the second set.
The returned statistic uses ranks of nonzero differences, with its exact interpretation depending on the alternative.
The p-value reflects both the selected directional hypothesis and the method used to calculate it.

Example: Paired measurements

import numpy as np
from scipy.stats import wilcoxon

before = np.array([12, 15, 14, 10, 13])
after = np.array([10, 14, 13, 11, 12])
result = wilcoxon(before, after, alternative="two-sided")
print(result.statistic, result.pvalue)

Compares paired measurements and reports the signed-rank statistic and p-value.

When to use it

Before-and-after analysis

Compare measurements taken from the same subjects before and after an intervention.

Non-parametric paired comparison

Test paired observations when normality assumptions for a paired t-test are unsuitable.

Difference-array testing

Evaluate paired residual or model-output differences directly.

Interview questions

QWhat does scipy.stats.wilcoxon test?

It is a non-parametric test for two related paired samples. Its null hypothesis is that the paired samples come from the same distribution, equivalently that the distribution of their differences is symmetric about zero.

Follow-up: What does a two-sided alternative test? It tests a median difference of zero against a difference from zero.

QHow can the inputs be represented?

Supply x and y for paired measurements, or supply only x when it already contains the paired differences. The function returns the test statistic and the p-value determined by the selected alternative and method.

Follow-up: Why might supplying differences directly be preferable? It avoids recomputing differences and lets the caller control how numerical differences are formed.

QHow is the statistic defined?

For a two-sided test, the statistic is the smaller sum of ranks on either side of zero. For a one-sided test, it is the sum of ranks for positive differences.

Follow-up: How can zero differences be handled? The zero_method parameter selects the documented treatment of zero differences, with wilcox as the default.

scipy.stats.ttest_rel
scipy.stats.mannwhitneyu
scipy.stats.permutation_test
scipy.stats.rankdata

Source: wilcoxon. Checked 2026-10-15.