Natural Sorting for Python

8.4.0 · active · verified Sun Mar 29

natsort is a Python library that provides 'natural' sorting capabilities, enabling lists containing numbers (e.g., filenames, version strings) to be sorted numerically rather than strictly lexicographically. It's a versatile tool that handles various data types and offers extensive customization. The current version is 8.4.0, and the library is actively maintained with a regular release cadence.

Warnings

breaking The default behavior of `natsorted()` changed in version 4.0.0. Prior to 4.0.0, it defaulted to sorting by 'real numbers' (signed floats). From 4.0.0 onwards, it prioritizes proper version number sorting by default.
Fix: If you relied on the old float-sorting default, explicitly use `realsorted()` or `natsorted(..., alg=ns.REAL)` for consistency. For version sorting, the new default is usually what you want.
breaking Version 8.0.0 introduced type hints throughout the codebase. While generally backward-compatible, this could potentially impact projects with very strict static analysis configurations or unusual introspection needs.
Fix: Ensure your environment and tooling are compatible with type-hinted code. Most users will not experience issues.
gotcha `natsorted()` returns a *new* sorted list and does not sort in-place, mimicking Python's built-in `sorted()` function. If you need to sort a list in-place, you must reassign the result or use `list.sort()` with a key.
Fix: To sort in-place, either reassign: `my_list = natsorted(my_list)` or use `my_list.sort(key=natsort_keygen())`.
gotcha For reliable locale-aware sorting (e.g., using `humansorted` or `alg=ns.LOCALE`), especially on non-Windows systems, installing `PyICU` is highly recommended. Python's standard `locale` module can be inconsistent or produce poor results for special characters.
Fix: Install `PyICU` (`pip install PyICU`) to ensure robust locale-sensitive sorting behavior across different operating systems.
gotcha `natsort` explicitly does not support sorting byte strings directly on Python 3 due to the complexities of guessing encoding for comparison. Attempting to sort mixed byte/string lists or raw byte lists may lead to unexpected results or errors.
Fix: Convert byte strings to regular Python strings (e.g., using `.decode('utf-8')`) before passing them to `natsorted()` or related functions.

Install

pip install natsort Install natsort

Imports

natsorted
```
from natsort import natsorted
```
The primary function for natural sorting, returns a new sorted list.
natsort_keygen
```
from natsort import natsort_keygen
```
Used to generate a key for in-place sorting with 'list.sort()'.
ns
```
from natsort import ns
```
Provides algorithm options (e.g., ns.FLOAT, ns.LOCALE) for advanced customization.
os_sorted
```
from natsort import os_sorted
```
Convenience function (added in v7.1.0) to sort paths like a file browser.
humansorted
```
from natsort import humansorted
```
Convenience function for locale-aware sorting (equivalent to natsorted with alg=ns.LOCALE).
realsorted
```
from natsort import realsorted
```
Convenience function for sorting by real numbers (equivalent to natsorted with alg=ns.REAL).

Quickstart

Demonstrates the basic usage of `natsorted()` to naturally sort a list of strings containing numbers. The `natsorted()` function acts as a drop-in replacement for Python's built-in `sorted()`.

from natsort import natsorted

unsorted_list = ['file1.txt', 'file10.txt', 'file2.txt', 'file_2.jpeg', 'file_1.png', 'file_10.gif']
sorted_list = natsorted(unsorted_list)

print(sorted_list)
# Expected output: ['file_1.png', 'file1.txt', 'file_2.jpeg', 'file2.txt', 'file_10.gif', 'file10.txt']

view raw JSON →