Python

Python statistics — mean, median, mode, and spread

A list of numbers usually needs a summary before it needs a chart: the typical value, the middle value, the most common value, and a sense of how far the values spread out. The statistics module computes all of those, plus quantiles, correlation, and a normal distribution type. This guide takes the center first, then the other means, spread, quantiles, relationships between two series, and the errors that empty or short data raise.

Written November 13, 2026 · Tested with Python 3.12.3 · 10 min read

By the end of this guide
  • The main program: mean, median, and mode
  • Median variants and fmean
  • Geometric and harmonic means, and exact types
  • Spread: variance and standard deviation

Written November 13, 2026

Tested with Python 3.12.3

What this guide is

The statistics module holds functions for numeric data: averages, measures of spread, quantiles, and the relationship between two series. The functions accept lists and other iterables of ints, floats, fractions, and decimals. Most results keep the input type where that makes sense, so the mean of a set of fractions is a fraction. A separate set of functions, whose names start with p, treats the data as a whole population rather than as a sample from one.

The main program: mean, median, and mode

The mean call adds the values and divides by the count. The median call returns the middle value, or the mean of the two middle values when the count is even. The mode call returns the most common value, and multimode returns every value tied for most common, as a list:

Python
import statistics
data = [2, 4, 4, 4, 5, 5, 7, 9]
print(statistics.mean(data))
print(statistics.median(data))
print(statistics.mode(data))
print(statistics.multimode(data))
print(type(statistics.mean(data)).__name__)

The exact output:

Output
5
4.5
4
[4]
int

The three center values answer three different questions. The mean uses every value, so one very large value pulls it up. The median uses position only, so that same large value moves it little or not at all. The mode ignores both size and position and reports what occurs most often. The last line shows the type rule: the mean of ints that divides evenly comes back as an int, not as a float.

Median variants and fmean

Three more median calls cover the cases where the plain median is not the value a job needs. The low and high medians return an actual data value instead of the mean of the middle pair. The grouped median works on data that was collected in groups. The fmean call always returns a float, and it runs faster than mean on long float lists:

Python
import statistics
print(statistics.median_low([1, 3, 5, 7]))
print(statistics.median_high([1, 3, 5, 7]))
print(statistics.median([1, 3, 5, 7]))
print(statistics.median_grouped([1, 2, 2, 3, 4, 4, 4], interval=1))
print(statistics.fmean([2, 4, 4, 4, 5, 5, 7, 9]))
print(statistics.fmean([1, 2, 3]))

The exact output:

Output
3
5
4.0
3.0
5.0
2.0

For an even count, the plain median of 1, 3, 5, and 7 is 4.0, a value that is not in the data. The low median returns 3 and the high median returns 5, and both are in the data. Code that needs a real member of the set — a median customer, a median file, a median day — should use one of those two. Code that reports a summary figure can use the plain median.

Geometric and harmonic means, and exact types

Two more means fit data that plain addition does not describe. The geometric mean fits values that grow by multiplication, such as growth factors across years. The harmonic mean fits rates, such as speeds over equal distances. The plain mean keeps exact input types:

Python
import statistics
from fractions import Fraction
from decimal import Decimal
print(statistics.geometric_mean([1, 4, 16]))
print(statistics.harmonic_mean([2, 4, 4]))
print(statistics.mean([Fraction(1, 2), Fraction(3, 2)]))
print(statistics.mean([Decimal("1.5"), Decimal("2.5")]))
print(type(statistics.mean([1, 2, 3])).__name__)

The exact output:

Output
4.0
3.0
1
2
int

The geometric mean of 1, 4, and 16 is 4.0, the middle factor, while the plain mean of the same list is 7. A growth report that uses the plain mean overstates the typical step. The fraction and decimal lines show the exact-type rule again: the mean of two fractions is the fraction 1, and the mean of two decimals is the decimal 2. Money and ratio code that must stay exact should pass those types in rather than converting to float at the start.

Spread: variance and standard deviation

Spread measures how far values sit from their mean. The variance is the mean of the squared distances, and the standard deviation is its square root, which brings the unit back to the unit of the data. Each one comes in two forms. The plain forms treat the data as a sample and divide by the count minus one. The p forms treat the data as the whole population and divide by the count:

Python
import statistics
data = [2, 4, 4, 4, 5, 5, 7, 9]
print(statistics.pvariance(data))
print(statistics.variance(data))
print(statistics.pstdev(data))
print(round(statistics.stdev(data), 6))
print(statistics.pstdev([5, 5, 5]))

The exact output:

Output
4
4.571428571428571
2.0
2.13809
0.0

The sample variance is larger than the population variance for the same data, because the smaller divisor makes up for the fact that a sample tends to sit closer to its own mean than to the population mean. Pick the form by what the data is. Data that covers every case — all files in a folder, all days in a month — is a population. Data drawn from a larger set is a sample. The last line is the floor case: a list with no spread at all returns 0.0.

Quantiles

The quantiles call cuts sorted data into n equal parts and returns the cut points. With n equal to 4 the cuts are the quartiles. The default method is exclusive, which treats the median as dividing the data into two halves. The inclusive method is the form most spreadsheet programs use, so the two methods give different first and third cuts on the same data:

Python
import statistics
data = [1, 2, 3, 4, 5, 6, 7, 8]
print(statistics.quantiles(data, n=4))
print(statistics.quantiles(data, n=4, method="inclusive"))
print(statistics.quantiles(data, n=2))
print(statistics.quantiles(data, n=10)[0])

The exact output:

Config
[2.25, 4.5, 6.75]
[2.75, 4.5, 6.25]
[4.5]
0.9

The middle cut agrees under both methods, because both put the median at 4.5. The other cuts do not agree, so a report that compares its quartiles against a spreadsheet must name the method it used, or the numbers look wrong when both are right. With n equal to 2 the only cut is the median. With n equal to 10 the cuts are the deciles, and the first one is 0.9 for this data.

Two series: covariance, correlation, and regression

Three functions describe how two series move together. Covariance is positive when both series rise together and negative when one falls as the other rises, but its size depends on the units of both series. Correlation scales that value into the range from -1 to 1, so it can be compared across pairs. The linear regression call returns the slope and intercept of the line that best fits the pairs:

Python
import statistics
x = [1, 2, 3, 4, 5]
y = [2, 4, 5, 4, 5]
print(statistics.covariance(x, y))
print(round(statistics.correlation(x, y), 6))
slope, intercept = statistics.linear_regression(x, y)
print(slope)
print(intercept)
print(round(statistics.correlation(x, x), 6))

The exact output:

Output
1.5
0.774597
0.6
2.2
1.0

A correlation of about 0.77 is a strong upward link, short of a perfect one. A series compared with itself returns exactly 1.0, which is a useful check when wiring the calls up. The regression line for this data rises 0.6 for each step in x and starts at 2.2. Correlation describes the link in the data given; it says nothing about which series causes the other, and a short series can show a strong value by chance.

The normal distribution, and errors on short data

The NormalDist type models a normal distribution from a mean and a standard deviation. It reports the chance of a value at or below a point, the point at a given chance, a score in standard deviations from the mean, and the density at a point. Bad input to the module functions raises StatisticsError, a subclass of ValueError. Empty data has no mean, and a sample spread needs at least two points:

Python
import statistics
from statistics import NormalDist
nd = NormalDist(mu=100, sigma=15)
print(round(nd.cdf(115), 6))
print(round(nd.inv_cdf(0.5), 6))
print(nd.zscore(115))
print(round(nd.pdf(100), 6))
try:
    statistics.mean([])
except statistics.StatisticsError as e:
    print(type(e).__name__)
try:
    statistics.stdev([5])
except statistics.StatisticsError as e:
    print(type(e).__name__)
try:
    statistics.correlation([1, 2], [1])
except statistics.StatisticsError as e:
    print(type(e).__name__)

The exact output:

Output
0.841345
100.0
1.0
0.026596
StatisticsError
StatisticsError
StatisticsError

A value one standard deviation above the mean sits at about the 84th percentile, which is what the first line reports. The inverse call at 0.5 returns the mean itself, as it should for a symmetric distribution. The error cases share one shape: each call states the least it needs — one point for a mean or median is still not enough when the data is empty, two points for a sample spread or a correlation, and equal lengths for the two-series calls. Code that reads data from a file should check those counts before the call, or catch StatisticsError and report the short data as the problem it is.

Which choice for which job

Job Choice Why
Typical value mean or fmean Uses every value
Middle value median Position only, resists outliers
Most common value mode Counts occurrences
Median that is a real member median_low or median_high Returns a data value
Spread of all cases pstdev Population form
Spread of a drawn sample stdev Sample form, count minus one
Quartile cuts quantiles Name the method used
Link between two series correlation Scaled from -1 to 1

Checklist

  • Pick the center by the question: mean for a typical value, median against outliers, mode for the most common value.
  • Use median_low or median_high when the result must be a real member of the data.
  • Match the spread form to the data: p forms for a whole population, plain forms for a sample.
  • Name the quantiles method when comparing against a spreadsheet, because exclusive and inclusive cuts differ.
  • Read correlation as a description of the data given, not as proof that one series causes the other.
  • Guard empty and one-point data before the call, or catch StatisticsError and report it.

Sources

  • Python Standard Library, statistics — mean, fmean, geometric and harmonic means, median and its low, high, and grouped forms, mode and multimode, variance and standard deviation in population and sample forms, quantiles, covariance, correlation, linear regression, NormalDist, and StatisticsError.

Keep Exploring