# How to Perform Custom Sorting in pandas DataFrames Using pandas sort values

> Learn how to perform custom sorting in pandas DataFrames with sort values. Effortlessly apply custom logic using the key parameter for powerful data manipulation.

- Repository: [pandas/pandas](https://github.com/pandas-dev/pandas)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Use the `key` parameter in `DataFrame.sort_values()` to apply a vectorized transformation to columns before sorting, enabling custom logic like sorting by string length or absolute value without modifying the original data.**

The `pandas sort values` method provides flexible, high-performance sorting for tabular data in the pandas-dev/pandas repository. Whether you need to reorder rows by calculated metrics or implement complex multi-column logic, understanding how to leverage the `key` parameter and sort algorithms unlocks powerful data manipulation capabilities.

## Understanding the pandas sort values Architecture

The implementation of `pandas sort values` spans multiple core modules to separate DataFrame-specific validation from generic sorting logic.

In **[`pandas/core/frame.py`](https://github.com/pandas-dev/pandas/blob/main/pandas/core/frame.py)**, the `DataFrame.sort_values` method serves as the entry point, defined starting at line 7917. This method validates the `by` argument (accepting column names or index levels) and forwards the call to the shared implementation.

The heavy lifting occurs in **[`pandas/core/generic.py`](https://github.com/pandas-dev/pandas/blob/main/pandas/core/generic.py)** within `NDFrame.sort_values` (lines 4870-4950). This generic routine normalizes parameters, applies the optional `key` function, delegates to low-level sorting utilities in **[`pandas/core/algos.py`](https://github.com/pandas-dev/pandas/blob/main/pandas/core/algos.py)**, and constructs the sorted result. The `Series.sort_values` implementation in [`pandas/core/series.py`](https://github.com/pandas-dev/pandas/blob/main/pandas/core/series.py) follows an analogous pattern for single-column operations.

## Custom Sorting with the key Parameter in pandas sort values

Introduced in pandas 1.1.0, the `key` parameter accepts a **vectorized callable** that receives each column (as a `Series`) and must return a `Series` of the same shape. The returned values are used as the sort keys, enabling transformations like string length, absolute value, or case-insensitive ordering.

### Sort Strings by Length Using pandas sort values

To reorder rows based on the character count of a string column, pass a lambda that computes `str.len()` to the `key` parameter:

```python
import pandas as pd

df = pd.DataFrame({
    "city": ["Paris", "Tokyo", "Berlin", "New York", "Sydney"],
    "population": [2.2, 13.9, 3.6, 8.4, 5.3]
})

# Sort by length of city name (shortest → longest)

sorted_df = df.sort_values(
    by="city",
    key=lambda s: s.str.len()
)

```

### Sort by Absolute Value with pandas sort values

When negative values should be ordered by magnitude regardless of sign, use the `abs()` method inside the `key` callable:

```python
import numpy as np

df = pd.DataFrame({
    "value": [10, -25, -5, 30, -15]
})

# Sort by absolute value, descending

sorted_df = df.sort_values(
    by="value",
    ascending=False,
    key=lambda s: s.abs()
)

```

### Multi-Column Custom Sorting Strategies

For complex logic involving multiple columns, dispatch different transformations based on the column name. The `key` callable receives each column individually, so inspect `s.name` to apply conditional logic:

```python
df = pd.DataFrame({
    "city": ["Paris", "Tokyo", "Berlin", "New York", "Sydney"],
    "temp": [12, 16, 8, 11, 20]
})

# Sort by city name length (ascending), then by temp (descending)

sorted_df = df.sort_values(
    by=["city", "temp"],
    ascending=[True, False],
    key=lambda s: s.str.len() if s.name == "city" else s
)

```

## Ensuring Stable Sorts with the kind Parameter

The `kind` parameter in `pandas sort values` selects the underlying NumPy algorithm: `quicksort`, `mergesort`, `heapsort`, or `stable`. For multi-column custom sorting where ties must preserve the original row order, use `mergesort` or `stable`:

```python
sorted_df = df.sort_values(
    by=["city", "temp"],
    ascending=[True, True],
    kind="stable",  # Preserves original order when keys are equal

    key=lambda s: s.str.len() if s.name == "city" else s
)

```

Stable algorithms are essential when the `key` function produces identical values for multiple rows and you need deterministic, reproducible ordering.

## In-Place Operations and Index Management

To modify the DataFrame without creating a copy, set `inplace=True`. Combine this with `ignore_index=True` to reset the index to a simple `RangeIndex` (0 to n-1) after sorting:

```python
df.sort_values(
    by="population",
    inplace=True,
    ignore_index=True,
    ascending=False
)

```

This pattern is memory-efficient for large datasets and ensures the resulting DataFrame has a clean, sequential index suitable for subsequent positional operations.

## Summary

- **`pandas sort values`** provides flexible sorting through `DataFrame.sort_values` in [`pandas/core/frame.py`](https://github.com/pandas-dev/pandas/blob/main/pandas/core/frame.py) and the shared `NDFrame.sort_values` implementation in [`pandas/core/generic.py`](https://github.com/pandas-dev/pandas/blob/main/pandas/core/generic.py).
- The **`key`** parameter enables vectorized custom transformations (string length, absolute value, etc.) without altering original data, receiving each column as a `Series`.
- Use **`kind="stable"`** or **`kind="mergesort"`** for deterministic multi-column sorts that preserve the original order of tied rows.
- Set **`inplace=True`** and **`ignore_index=True`** for memory-efficient sorting with a reset index.

## Frequently Asked Questions

### How does the key parameter in pandas sort values work?

The `key` parameter accepts a vectorized callable that receives each column specified in `by` as a pandas `Series`. The function must return a `Series` of the same shape, which pandas uses as the actual sort key. This allows you to sort by derived values like string length or absolute magnitude without creating temporary columns.

### When should I use kind="stable" in pandas sort values?

Use `kind="stable"` (or `kind="mergesort"`) when performing multi-column custom sorts where the `key` function might produce identical values for multiple rows. Stable algorithms guarantee that the original order of these tied rows is preserved, ensuring deterministic and reproducible results across multiple runs.

### Can I apply different key functions to different columns in pandas sort values?

Yes, but because the `key` callable receives each column individually, you must inspect the `Series.name` attribute to dispatch different logic. For example, use `lambda s: s.str.len() if s.name == "city" else s` to sort the "city" column by length while sorting other columns by their raw values.

### What is the difference between inplace=True and ignore_index=True in pandas sort values?

`inplace=True` modifies the DataFrame directly without returning a new object, saving memory on large datasets. `ignore_index=True` resets the index to a sequential `RangeIndex` (0 to n-1) after sorting, which is useful when the original index values are no longer meaningful after reordering. These parameters can be used together or independently.