Natural Sorting for Python

raw JSON →
8.4.0 verified Tue May 12 auth: no python install: verified

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.

pip install natsort

Common errors

error ModuleNotFoundError: No module named 'natsort' ↓
cause The 'natsort' package is not installed in the Python environment you are currently using, or the environment is not correctly configured.
fix
Install the 'natsort' package using pip: pip install natsort
error TypeError: '<' not supported between instances of 'str' and 'int' ↓
cause This error occurs when attempting to sort a list containing a mix of incompatible data types (e.g., strings and integers) where Python's underlying sorting mechanism, even when wrapped by `natsort`, cannot establish a consistent comparison order.
fix
Ensure all elements in the list are of compatible types, or provide a key function to natsorted that converts elements to a common comparable type (e.g., str or int) before comparison. For example: natsorted(my_list, key=str) or natsorted(my_list, key=lambda x: int(x) if x.isdigit() else x) if you know all numbers are digits.
error natsort not sorting correctly ↓
cause Users often encounter unexpected sorting order because the default `natsorted()` function or its specific variants (`humansorted()`, `realsorted()`, `os_sorted()`) are not configured with the correct algorithm parameters (`alg`) or a custom `key` function to achieve the desired 'natural' sorting for their specific data (e.g., signed floats, locale-specific strings, or complex objects).
fix
Review the natsort documentation to select the appropriate sorting function (natsorted, humansorted, realsorted, os_sorted) and/or algorithm flag (alg parameter) that matches your data's characteristics. For example, use realsorted() for lists with real numbers, humansorted() for locale-aware sorting, or provide a key function for custom objects or specific data extraction.

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 compatibility verified last tested: 2026-05-12 v8.4.0 (up to date)

python os / libc status wheel install import disk mem side effects
3.10 alpine (musl) wheel - 0.09s 18.0M 2.7M clean
3.10 alpine (musl) - - 0.10s 18.0M 2.7M -
3.10 slim (glibc) wheel 1.4s 0.05s 19M 2.7M clean
3.10 slim (glibc) - - 0.06s 19M 2.7M -
3.11 alpine (musl) wheel - 0.15s 19.9M 2.5M clean
3.11 alpine (musl) - - 0.18s 19.9M 2.5M -
3.11 slim (glibc) wheel 1.6s 0.14s 20M 2.5M clean
3.11 slim (glibc) - - 0.13s 20M 2.5M -
3.12 alpine (musl) wheel - 0.11s 11.8M 2.2M clean
3.12 alpine (musl) - - 0.13s 11.8M 2.2M -
3.12 slim (glibc) wheel 1.4s 0.12s 12M 2.2M clean
3.12 slim (glibc) - - 0.14s 12M 2.2M -
3.13 alpine (musl) wheel - 0.10s 11.5M 2.1M clean
3.13 alpine (musl) - - 0.11s 11.4M 2.1M -
3.13 slim (glibc) wheel 1.4s 0.11s 12M 1.9M clean
3.13 slim (glibc) - - 0.12s 12M 1.9M -
3.9 alpine (musl) wheel - 0.08s 17.5M 2.6M clean
3.9 alpine (musl) - - 0.09s 17.5M 2.6M -
3.9 slim (glibc) wheel 1.7s 0.06s 18M 2.6M clean
3.9 slim (glibc) - - 0.07s 18M 2.6M -

Imports

Quickstart last tested: 2026-04-24

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']
last verified Tue May 12
next check Sat Jun 27