Skip to main content
v2026.11,986 entries · CC-BY 4.0

pandas nunique: How to Count Unique Values in Python

How pandas nunique() counts distinct values: DataFrame and Series syntax, dropna and axis, a survey worked example, common errors and alternatives.

Written and maintained by CASRAI Editorial Board

Published

On this page

In pandas, nunique() counts the distinct values in a Series or along an axis of a DataFrame. df.nunique() returns a Series with one count per column, series.nunique() returns a single integer, and by default missing values (NaN) are left out of the count. Pass dropna=False to count a missing value as one more distinct value, or axis=1 to count distinct values across each row instead of down each column.

This guide uses the official pandas documentation for the signature and defaults and a small research-survey table to show what each argument changes. Every output printed below was produced by running the code in pandas 3.1.1, the version of the documentation read for this page.

What pandas nunique is used for in research

Researchers use nunique() to measure the number of distinct categories, participants, sites or identifiers in a dataset before any modelling starts. The pandas documentation describes DataFrame.nunique as counting the “number of distinct elements in specified axis” and returning a Series that can ignore NaN values, which is exactly the summary a data-cleaning pass needs.

Typical research uses include:

  • Checking identifier columns. If a participant or sample ID column should be unique per row, df['id'].nunique() compared with len(df) shows immediately whether IDs repeat. The gap is the number of rows that repeat an earlier ID.
  • Counting categories. The number of distinct sites, arms, instruments or response options per column tells you whether a variable behaves as a binary, a small categorical or a free-text field.
  • Counting distinct answers per respondent. With axis=1 you can see how many different answers one respondent gave across a block of items, which flags straight-lining (the same answer to every item).
  • Auditing data after a merge. Comparing distinct counts before and after a join reveals duplicated or lost keys. For the removal step itself, see the CASRAI guides on flagging duplicates with pandas duplicated and removing them with drop_duplicates.

Counting distinct values is a descriptive check, not a statistical test. It tells you how many different values exist, not how often each occurs; for frequencies use value_counts (see the alternatives section).

How to install or access pandas

The pandas installation page lists two supported routes. With the pip package manager, pandas is installed from PyPI with:

pip install pandas

With the Conda package manager, pandas is installed from the conda-forge channel:

conda install -c conda-forge pandas

The pandas documentation also recommends installing and running pandas from a virtual environment. For Conda that is:

conda create -c conda-forge -n name_of_my_env python pandas
conda activate name_of_my_env

With pip, Python’s standard-library venv module creates a lightweight virtual environment with its own independent set of installed packages, isolated by default from the packages in the base environment. A virtual environment per project keeps the pandas version you used for an analysis from changing underneath you, which matters when the analysis has to be reproduced later. The installation page lists NumPy and python-dateutil among the required dependencies and pip installs them for you.

Once installed, no extra import is needed for nunique: it is a method on every pandas Series and DataFrame.

import pandas as pd
import numpy as np

How to count unique values with nunique step by step

The example below is an illustrative composite: a six-row survey table invented for this guide, not data from any real study. Respondent R03 appears twice with different answers to q2, one respondent has no site recorded, and one has no answer to q2.

Step 1: build or load the table

  1. Create the DataFrame (in real work you would use pd.read_csv or a similar reader):
df = pd.DataFrame({
    "respondent_id": ["R01", "R02", "R03", "R03", "R04", "R05"],
    "site": ["Leeds", "Leeds", "Oslo", "Oslo", "Oslo", np.nan],
    "q1": ["yes", "no", "yes", "yes", "no", "yes"],
    "q2": ["yes", "yes", "yes", "no", "no", np.nan],
})

Step 2: pandas nunique on a whole DataFrame

  1. Call nunique() with no arguments. The signature is DataFrame.nunique(axis=0, dropna=True), so this counts distinct values down each column and ignores NaN:
df.nunique()

respondent_id    5
site             2
q1               2
q2               2
dtype: int64

The result is a Series indexed by column name. There are six rows but five distinct respondent IDs, because R03 repeats.

Step 3: count NaN as a value with dropna=False

  1. Set dropna=False to include missing values in the count:
df.nunique(dropna=False)

respondent_id    5
site             3
q1               2
q2               3
dtype: int64

site rises from 2 to 3 and q2 from 2 to 3, because the single missing value in each column now counts as one extra distinct value. The columns with no missing values do not change. The difference between the two calls is a fast way to see which columns contain missing data.

Step 4: nunique on one column (Series.nunique)

  1. Select a column and call the Series method. Series.nunique(dropna=True) returns a single integer and, per the documentation, excludes NA values by default:
df["site"].nunique()               # 2
df["site"].nunique(dropna=False)   # 3

Step 5: pandas nunique across rows with axis=1

  1. Use axis=1 (or axis='columns') to count distinct values within each row. Applied to the two question columns:
df[["q1", "q2"]].nunique(axis=1)

0    1
1    2
2    1
3    2
4    1
5    1
dtype: int64

A 1 means the respondent gave the same answer to both items (or answered only one, since NaN is ignored); a 2 means two different answers. Row 5 shows 1 even though q2 is missing, which is the dropna=True default at work.

Step 6: check that an ID column is unique

  1. Compare the distinct count with the row count:
df["respondent_id"].nunique() == len(df)    # False
len(df) - df["respondent_id"].nunique()     # 1

The comparison is False and the difference is 1, so one row repeats an earlier ID. To see which row repeats and to remove it, use the duplicated and drop_duplicates approaches linked earlier in this guide.

Step 7: distinct counts within groups

  1. Group first, then count distinct IDs in each group, side by side with the plain row count:
df.groupby("site")["respondent_id"].agg(["count", "nunique"])

       count  nunique
site
Leeds      2        2
Oslo       3        2

Oslo has three rows but two distinct respondents. Rows with a missing site drop out of the grouping by default. Reporting distinct respondents per site, rather than rows per site, is the figure a methods section normally needs when respondents can appear more than once.

How to read the output

Read the return type first. DataFrame.nunique returns a Series of counts, one per column when axis=0 and one per row when axis=1; Series.nunique returns an integer. The counts are integers (dtype int64 in the documentation examples).

What a count does and does not tell you

  • A count of distinct values equals the number of rows only for a column with no repeats and no missing values. In the example, respondent_id has 5 distinct values in 6 rows.
  • A count of 1 in a column means every non-missing value is identical, so the column carries no variation and is usually safe to drop from a model.
  • A count near the row count in a text column suggests free text or an identifier rather than a category.
  • Distinct is not the same as non-missing. DataFrame.count counts non-NA cells, and the documentation lists None, NaN, NaT and pandas.NA as NA values. In the example df.count() returns 6, 5, 6, 5 for the four columns, while df.nunique() returns 5, 2, 2, 2.

How values are matched

Two values count as the same only if pandas treats them as equal. In a test with pandas 3.1.1, pd.Series(["Oslo", "oslo", "Oslo ", "Leeds"]).nunique() returns 4, because case and trailing spaces make three different strings. After .str.strip().str.lower() the same Series returns 2. A text string “1” and the number 1 are also counted as different values, while 1 and 1.0 are counted as one. Clean text before counting if inconsistent spelling is possible.

Troubleshooting nunique

Why does a list-valued column raise “unhashable type: ‘list'”?

Counting distinct values needs hashable entries. In pandas 3.1.1, pd.Series([[1], [2], [1]]).nunique() raises TypeError: unhashable type: 'list'. Convert each list to a tuple (for example s.apply(tuple).nunique()) or split the lists into separate columns first.

Why does a plain list have no nunique?

nunique is a method of pandas objects, so [1, 2, 2].nunique() raises AttributeError: 'list' object has no attribute 'nunique'. Wrap the list in pd.Series(...) first.

Why do I get a bound method instead of numbers?

Writing df.nunique without parentheses returns the method object, printed as bound method DataFrame.nunique of .... Call it as df.nunique().

Why is my count one higher than I expected?

Check whether you passed dropna=False, which counts missing values as a distinct value. With the default dropna=True, NaN is excluded. Also look for near-duplicate spellings and mixed types, described above.

Why does a pandas-on-Spark example show an extra argument?

Search results often mix pandas with the Spark implementation of the pandas API. The pandas documentation for DataFrame.nunique lists only axis and dropna; check that the page you follow is on pandas.pydata.org.

Free alternatives to nunique

Every option below is free and open source. They answer slightly different questions, which is why the choice is not only about speed or style.

Function Answers the question Difference from nunique
Series.value_counts() How often does each distinct value occur? Returns a Series of counts per value, sorted in descending order by default; dropna=True by default, like nunique. The number of distinct values is the length of the result.
Series.unique() Which distinct values are there? Returns the values themselves in order of appearance (hash table-based, not sorted), not a count. In the example, len(df["site"].unique()) returns 3 because the missing value appears in the array; nunique() returns 2.
DataFrame.count() How many cells have a value? Counts non-NA cells per column or row, repeats included.
numpy.unique(ar, return_counts=True) Distinct values and their counts in a NumPy array Returns the sorted unique elements, plus the number of times each occurs when return_counts is True. It works on arrays and does not take a dropna argument; its equal_nan option controls whether multiple NaN values collapse into one.

The data table below compares these four functions and Series.nunique against the documentation. For the NumPy route in depth, see the CASRAI guide to numpy.unique; for counting the number of times combinations of two categorical columns occur, see pandas crosstab; for counting rows and non-missing cells, see pandas count.

A practical rule that follows from the table: use nunique() when you need one number per column, value_counts() when you need the frequency of each value, and unique() when you need to see the values.

Sources

Data: Distinct-value counting functions in pandas and NumPy: return type and missing-value handling

Compares five documented functions that count or list distinct values (DataFrame.nunique, Series.nunique, Series.value_counts, Series.unique, numpy.unique): what each returns and how it treats missing values by default. Compiled from the official pandas and NumPy API reference pages.

Period covered: 2026-11 (pandas 3.1.1 documentation).

Distinct-value counting functions in pandas and NumPy: return type and missing-value handling
FunctionReturnsDefault missing-value handlingDocumented parameters controlling it
DataFrame.nuniqueSeries with the number of distinct elements per column (axis=0) or per row (axis=1)NaN ignored (dropna=True)axis, dropna
Series.nuniqueAn integer: the number of unique elementsNA values excluded by default (dropna=True)dropna
Series.value_countsSeries of counts of unique values, most frequent first by defaultNaN excluded (dropna=True)normalize, sort, ascending, bins, dropna
Series.uniqueUnique values in order of appearance, as a NumPy array or ExtensionArray; not sortedNot stated on the pagenone
numpy.uniqueSorted unique elements of an array, optionally with indices, inverse indices and countsMultiple NaN values collapse into one when equal_nan is Truereturn_index, return_inverse, return_counts, axis, equal_nan, sorted

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · full access

Ask about pandas nunique: How to Count Unique Values in Python

Full access: large monthly usage, up to 10 source passages behind each answer, and MCP and API access for Claude Code, Codex and other CLIs. Cancel any time.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →