natsort: Simple Yet Flexible Natural Sorting in Python

Welcome to the official documentation for natsort, a highly optimized, feature-rich library designed to perform natural sorting in Python.

Why Natural Sorting Matters

By default, Python's built-in sort() and sorted() functions use lexicographical (alphabetical) sorting. This compares strings character-by-character based on their Unicode code points. While mathematically predictable, this approach often fails to align with human intuition, particularly when strings contain embedded numbers.

Consider a standard list of numbered items:

>>> my_list = ['item-2', 'item-1', 'item-10', 'item-11']
>>> sorted(my_list)
['item-1', 'item-10', 'item-11', 'item-2']

Notice the problem? item-10 appears before item-2 because the character '1' has a lower ordinal value than '2'.

natsort solves this problem. It parses the strings, isolates the numbers, and evaluates them numerically rather than alphabetically, yielding a "natural" sort:

>>> from natsort import natsorted
>>> natsorted(my_list)
['item-1', 'item-2', 'item-10', 'item-11']

Key Features

natsort goes far beyond basic integer extraction. It is a mature, production-ready library designed to handle edge cases that frequently break naive custom sorting algorithms.

  • Drop-in Replacement: Use natsorted() exactly like you would the built-in sorted() function. It accepts the same key and reverse arguments.
  • OS-Native File Path Sorting: Mimic the exact sorting behavior of your operating system's native file browser (Windows Explorer, macOS Finder, Linux Nautilus) using os_sorted().
  • Semantic Versioning: Naturally sorts software version strings out-of-the-box (1.9.9 vs 1.10.0).
  • Float and Scientific Notation: Can parse and evaluate signed floating-point numbers and exponential notation (e.g., 5.3e10) using the ns.REAL flag.
  • Mixed Data Types: Safely sorts collections containing a mix of int, float, and str types without raising Python's dreaded TypeError: '<' not supported between instances.
  • Locale-Aware Parsing: Handles localized thousands separators and decimal markers appropriately using the PyICU integration.
  • Customizable Architecture: Leverage the ns Enum to tweak casing rules, NaN handling, and grouping logic via bitwise flags.
  • Command-Line Interface: Sort text output seamlessly from your terminal via stdin piping.

How it Works Under the Hood

At a high level, natsort avoids massive try/except blocks during comparison by generating a stable sorting key. The natsort_keygen() function splits strings into tuples alternating between string prefixes and numerical values.

For example, "apple15.5" becomes ("apple", 15.5). Python's native tuple comparison then effortlessly handles the heavy lifting, comparing the strings alphabetically and the numbers numerically.

Where to Go Next

  • Installation: Learn how to install natsort and its optional performance extensions.
  • Quick Start: A fast tutorial to get your first script running.
  • Usage Guide: Deep dive into advanced use cases, locale sorting, and configurations.
  • API Reference: Detailed documentation of all functions, classes, and Enums.