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 withlen(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=1you 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
- Create the DataFrame (in real work you would use
pd.read_csvor 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
- Call
nunique()with no arguments. The signature isDataFrame.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
- Set
dropna=Falseto 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)
- 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
- Use
axis=1(oraxis='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
- 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
- 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_idhas 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.countcounts non-NA cells, and the documentation lists None, NaN, NaT and pandas.NA as NA values. In the exampledf.count()returns 6, 5, 6, 5 for the four columns, whiledf.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
- pandas documentation: pandas.DataFrame.nunique, checked 2026-11-17
- pandas documentation: pandas.Series.nunique, checked 2026-11-17
- pandas documentation: pandas.DataFrame.count, checked 2026-11-17
- pandas documentation: pandas.Series.value_counts, checked 2026-11-17
- pandas documentation: pandas.Series.unique, checked 2026-11-17
- pandas documentation: Installation, checked 2026-11-17
- NumPy documentation: numpy.unique, checked 2026-11-17
- Python documentation: venv, creation of virtual environments, checked 2026-11-17
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).
| Function | Returns | Default missing-value handling | Documented parameters controlling it |
|---|---|---|---|
| DataFrame.nunique | Series with the number of distinct elements per column (axis=0) or per row (axis=1) | NaN ignored (dropna=True) | axis, dropna |
| Series.nunique | An integer: the number of unique elements | NA values excluded by default (dropna=True) | dropna |
| Series.value_counts | Series of counts of unique values, most frequent first by default | NaN excluded (dropna=True) | normalize, sort, ascending, bins, dropna |
| Series.unique | Unique values in order of appearance, as a NumPy array or ExtensionArray; not sorted | Not stated on the page | none |
| numpy.unique | Sorted unique elements of an array, optionally with indices, inverse indices and counts | Multiple NaN values collapse into one when equal_nan is True | return_index, return_inverse, return_counts, axis, equal_nan, sorted |
Sources
- pandas documentation: pandas.DataFrame.nunique (accessed 2026-11-17)
- pandas documentation: pandas.Series.nunique (accessed 2026-11-17)
- pandas documentation: pandas.Series.value_counts (accessed 2026-11-17)
- pandas documentation: pandas.Series.unique (accessed 2026-11-17)
- NumPy documentation: numpy.unique (accessed 2026-11-17)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







