Quick answer: np.argpartition returns indices that place a kth boundary without fully sorting the array. It is useful for top-k or bottom-k selection: partition, take the selected slice, then sort that small slice only when ordered output is required.
numpy.argpartition() returns indices that place one or more kth elements into their sorted positions without fully sorting the whole array.
The official NumPy documentation covers numpy.argpartition(), numpy.partition(), and numpy.argsort().
Use argpartition() when you need indices for the smallest values, largest values, or a specific rank, but do not need a complete sorted order.
The result is an index array. Apply it to the original array to see the values in partitioned order.
The most important detail is that each partition is not fully sorted. Values before the kth position are less than or equal to the boundary value, and values after it are greater than or equal, but their internal order is unspecified.
That behavior is the point of the function. It can be faster than a full sort because it only does enough work to place the requested boundary positions correctly.
Use argsort() when the full sorted order matters. Use argpartition() when a rank boundary or top-k selection is enough.
For two-dimensional arrays, the axis argument controls whether partitioning happens across rows, down columns, or after flattening.
If you need top-k values in sorted order, first use argpartition() to select the small group, then sort only that group.
A useful way to think about the function is selection first, presentation second. The partition step chooses candidates efficiently; a separate small sort can make those candidates readable when needed.
Always keep the returned indices tied to the original array. If the values represent rows, labels, or records elsewhere, the indices are what let you recover the matching context.
Find The Smallest Values
Use a small kth value to put the smallest items near the front.
import numpy as np
values = np.array([40, 10, 30, 20, 50])
indices = np.argpartition(values, 2)
smallest_three = values[indices[:3]]
print(indices)
print(smallest_three)
The first three selected values are the three smallest values.
They may not appear in sorted order because the left partition is only partially ordered.
Sort the selected values afterward if display order matters.
This is useful when the goal is selection rather than full ranking.
For example, if you only need the three smallest distances from a much larger list, there is no need to fully sort every distance. The selected subset is enough for the next filtering step.
Find The Largest Values
Use a negative kth position to select from the high end.
import numpy as np
scores = np.array([72, 91, 84, 99, 67])
indices = np.argpartition(scores, -2)
top_two = scores[indices[-2:]]
print(indices)
print(top_two)
The last two selected values are the two largest scores.
They are not guaranteed to be sorted from low to high or high to low.
For reports, sort the selected subset after taking it from the original array.
For filtering, the unsorted subset is often enough.
When selecting top scores, use the same caution as with smallest values: the selected group contains the right candidates, but the group itself still needs sorting if rank order will be shown to users.
Sort The Selected Subset
Combine argpartition() with a small sort when the selected values need order.
import numpy as np
values = np.array([40, 10, 30, 20, 50])
indices = np.argpartition(values, 2)[:3]
ordered_indices = indices[np.argsort(values[indices])]
print(values[ordered_indices])
This first selects the three smallest values, then sorts only those three.
That avoids sorting the full array when only a small subset is needed.
This pattern is useful for leaderboards, nearest candidates, and quick previews.
Keep the original indices when the selected values must be traced back to records.
This two-step pattern is often faster than a full sort when the array is large and k is small. It also makes the code explicit about where selection ends and ordering begins.
Use argpartition Along Rows
Set axis=1 to partition values within each row.
import numpy as np
data = np.array([
[8, 2, 5],
[1, 9, 4],
])
indices = np.argpartition(data, 1, axis=1)
print(indices)
print(np.take_along_axis(data, indices, axis=1))
The index output is row-based, so take_along_axis() is the clearest way to apply it.
Each row is partitioned independently.
Use this form when each row is a separate record or sequence.
As with one-dimensional arrays, the partitions inside each row are not fully sorted.
If you need the two smallest values per row in sorted order, first take the selected columns from each row, then sort those selected values row by row.
Use argpartition Along Columns
Set axis=0 to partition down each column.
import numpy as np
data = np.array([
[8, 2, 5],
[1, 9, 4],
[6, 3, 7],
])
indices = np.argpartition(data, 1, axis=0)
print(np.take_along_axis(data, indices, axis=0))
This partitions each column independently.
The result can help select low or high values per feature, metric, or column.
Use take_along_axis() rather than manual indexing when applying per-axis indices.
This keeps the axis behavior explicit and avoids shape mistakes.
Column-wise partitioning is handy when each column is a separate metric and you want low or high rows per metric. It is less appropriate when columns do not share the same meaning across rows.
Compare argpartition And argsort
argsort() gives a full sorted order. argpartition() gives enough order to place the boundary.
import numpy as np
values = np.array([40, 10, 30, 20, 50])
partial = values[np.argpartition(values, 2)]
full = values[np.argsort(values)]
print(partial)
print(full)
The partitioned result is useful for selection, while the fully sorted result is useful for complete ranking.
Choose argpartition() for efficient top-k or bottom-k selection.
Choose argsort() when every value must be in final sorted order.
That distinction also affects readability. If a future reader expects a sorted array, argsort() is clearer. If the code is selecting candidates for another step, argpartition() communicates that only the boundary matters.
In short, use np.argpartition(values, kth) to get index positions for partial sorting, remember that partition order is not fully sorted, and apply a small final sort only when the selected subset needs presentation order.
Select The Smallest k
For k smallest values, partition at k-1 and take the first k indices. The selected values are not guaranteed to be sorted until you order them explicitly. Validate that k is positive and no greater than the selected dimension.
Sort The Selected Subset
If the result is for display or an API that promises order, sort the selected indices by their values after partitioning. This avoids fully sorting values that will be discarded and preserves the performance reason for choosing argpartition.
Use An Axis
Pass axis for multidimensional data and confirm the shape of the index result. The dimension being partitioned must match the meaning of k in the application, especially when selecting a top-k result for every row or column.
Handle Ties And Bounds
Ties may appear in any order around the kth boundary. Decide whether any tied item is acceptable or whether a deterministic secondary key is required. Test empty arrays, k equal to one, k equal to the dimension, and duplicate values.
Separate Selection From Presentation
argpartition is a selection primitive, not a presentation formatter. Keep the fast selection step separate from the optional final ordering step so readers can see both the performance choice and the output contract.
NumPy’s argpartition() reference defines kth, axis, and partial ordering. Related references include full sorting, axis semantics, and array reductions.
For related array selection, compare full sorting, axis semantics, and array reductions when choosing a top-k method.
Frequently Asked Questions
What does np.argpartition return?
It returns indices that partition values around a kth position without fully sorting the partitions.
How do I get the smallest k values?
Partition at k-1, take the first k indices, and sort that selected subset if ordered values are needed.
Is argpartition fully sorted?
No. Values on each side of the boundary are not guaranteed to be internally ordered.
Can argpartition work along an axis?
Yes. Pass axis to select the dimension and keep the resulting shapes aligned with the data.
