Pandas · Function

df.value_counts

Counts distinct row combinations in a DataFrame and returns them as a Series. You can restrict the counted columns, request proportions, control ordering, and include missing-value rows.

How it works

DataFrame.value_counts groups rows by the values in all columns or by columns named in subset, then returns a Series indexed by the distinct combinations. It can produce raw counts or proportions, control ordering, and either exclude or include rows containing missing values.

Syntax

DataFrame.value_counts(subset=None, normalize=False, sort=True, ascending=False, dropna=True)

Parameters

Name	Type	Description
`subset`	`Hashable or a sequence of Hashable, optional`	Columns to use when counting unique combinations.
`normalize`	`bool, default False`	Return proportions rather than frequencies.
`sort`	`bool, default True`	Sort by frequencies when True.
`ascending`	`bool, default False`	Sort in ascending order.
`dropna`	`bool, default True`	Do not include counts of rows that contain NA values.

Returns

A Series containing the frequency of each distinct row in the DataFrame.

Key points

The method returns a Series with one entry for each distinct row pattern.
Distinct combinations form the result index, allowing each frequency to be associated with its row values.
Use subset to restrict counting to selected columns instead of the entire DataFrame.
normalize=True changes the output from integer-like frequencies to relative proportions.
sort=True orders results according to their frequencies; setting it to False disables frequency sorting.
ascending=True reverses the usual descending frequency order when sorting is enabled.

Common mistakes

Missing values are excluded unless dropna=False; a row with an NA in any counted column is omitted by default.
The default output places the most frequent combinations first; use ascending=True to reverse the frequency order.

Example: Count values by selected column

import pandas as pd

df = pd.DataFrame({
    "color": ["red", "blue", "red", "red"],
    "size": ["S", "M", "S", "L"],
})

print(df.value_counts(subset=["color"], normalize=True))

Counts the distinct colors and returns their relative proportions instead of integer frequencies.

When to use it

Find repeated row patterns

Profile duplicate records or categorical combinations across a table.

Calculate category proportions

Measure the distribution of selected categorical dimensions.

Audit missing-value patterns

Inspect combinations while deciding whether missing values should participate.

Interview questions

QWhat does DataFrame.value_counts return?

It returns a Series whose index represents each distinct row combination and whose values are their frequencies. With subset, only the specified columns define the combinations.

Follow-up: What changes when normalize=True? It returns proportions rather than counts, so the values represent each combination's share of the counted rows.

QHow does subset affect the result?

subset selects the columns used to form unique combinations; if omitted, every DataFrame column participates. The result therefore distinguishes rows by the selected columns rather than necessarily by complete rows.

Follow-up: What index structure should be expected for multiple selected columns? The result uses a MultiIndex with one level for each input column.

QHow do normalize, sort, and ascending change the output?

normalize=False produces frequencies, while normalize=True produces proportions. sort controls whether results are ordered by frequency, and ascending controls the direction when sorting by frequency.

Follow-up: How can missing-value rows be counted? Set dropna=False so rows containing NA values are included.

DataFrame.nunique
DataFrame.drop_duplicates
Series.value_counts
DataFrameGroupBy.value_counts

Source: pandas.DataFrame.value_counts. Checked 2026-10-15.