NumPy · Function

np.unique

Finds the distinct elements of an array and returns them sorted by default. Optional outputs provide source positions, reconstruction indices, and occurrence counts.

How it works

NumPy first processes the input as a flattened array unless an axis is supplied, then returns sorted distinct values. Optional flags add first-occurrence indices, inverse indices that reconstruct the input, and per-value counts; axis mode compares subarrays instead of scalar elements.

Syntax

numpy.unique(ar, return_index=False, return_inverse=False, return_counts=False, axis=None, *, equal_nan=True, sorted=True)

Parameters

Name	Type	Description
`ar`	`array_like`	Input array.
`return_index`	`bool, optional`	If True, also return the indices of ar (along the specified axis, if provided, or in the flattened array) that result in the unique array.
`return_inverse`	`bool, optional`	If True, also return the indices of the unique array (for the specified axis, if provided) that can be used to reconstruct ar.
`return_counts`	`bool, optional`	If True, also return the number of times each unique item appears in ar.
`axis`	`int or None, optional`	The axis to operate on. If None, ar will be flattened. If an integer, subarrays indexed by the given axis will be flattened and treated as the elements of a 1-D array.
`equal_nan`	`bool, optional`	Whether NaN values are treated as equal.
`sorted`	`bool, optional`	Whether the unique elements are sorted.

Returns

The unique values, optionally followed by indices, inverse indices, and counts, depending on the requested boolean flags.

Key points

The primary result contains distinct values in sorted order.
return_index=True adds positions from the input corresponding to the unique result.
return_inverse=True provides mapping indices that can rebuild the input from the unique values.
return_counts=True adds an occurrence count for every unique item.
axis chooses the dimension over which uniqueness is evaluated.
The function signature includes equal_nan, which controls the treatment of NaN values.

Common mistakes

Without axis, multidimensional input is flattened before uniqueness is determined.
With an integer axis, uniqueness is computed over subarrays along that axis rather than individual scalars.

Example: Collect unique values and metadata

import numpy as np

values = np.array([3, 1, 3, 2, 1, 2])
unique, first, inverse, counts = np.unique(
    values, return_index=True, return_inverse=True, return_counts=True
)
print(unique)                 # [1 2 3]
print(first)                  # [1 3 0]
print(unique[inverse])        # [3 1 3 2 1 2]
print(counts)                 # [2 2 2]

This obtains sorted distinct values, their first positions, reconstruction indices, and occurrence counts.

When to use it

Extract distinct values

Deduplicating numeric or string data before downstream array processing.

Locate first occurrences

Recovering where each distinct value first appeared in an input sequence.

Create inverse labels

Encoding repeated values as compact integer labels for reconstruction or grouping.

Count occurrences

Computing frequency tables for array values.

Interview questions

QWhat does np.unique return by default, and what optional metadata can it provide?

By default, np.unique returns one sorted array containing each distinct value once. If requested, it can also return first-occurrence positions, inverse reconstruction indices, and occurrence counts.

Follow-up: How can the original array be reconstructed? Use the unique values indexed by the returned inverse array; equivalently, unique[inverse] reproduces the flattened input.

QHow does axis change np.unique behavior?

The axis argument selects the dimension along which subarrays are treated as elements. If axis is None, the input is flattened; otherwise, subarrays indexed by that axis are compared.

Follow-up: What happens to the selected subarrays internally? They are flattened and treated as elements of a one-dimensional array for uniqueness testing.

QWhat are the three optional index/count outputs used for?

return_index=True returns indices of the input that produce the unique values, while return_inverse=True returns indices into the unique result that can reconstruct the input. return_counts=True reports how often each unique item occurs.

Follow-up: Which index identifies the first occurrence of each unique value? The returned indices from return_index=True identify those first occurrences.

numpy.unique_all
numpy.unique_counts
numpy.unique_inverse
numpy.unique_values

Source: numpy.unique. Checked 2026-10-15.