Install & Compatibility
Where this runs
tested against v8.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.110s · 18MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.098s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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).
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']
Debug
Known issues
breakingThe 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.fixIf 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.
affects: <4.0.0 to >=4.0.0
breakingVersion 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.fixEnsure your environment and tooling are compatible with type-hinted code. Most users will not experience issues.
affects: >=8.0.0
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.fixTo sort in-place, either reassign: `my_list = natsorted(my_list)` or use `my_list.sort(key=natsort_keygen())`.
affects: All versions
gotchaFor 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.fixInstall `PyICU` (`pip install PyICU`) to ensure robust locale-sensitive sorting behavior across different operating systems.
affects: All versions
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.fixConvert byte strings to regular Python strings (e.g., using `.decode('utf-8')`) before passing them to `natsorted()` or related functions. affects: Python 3, all versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'natsort'
The 'natsort' package is not installed in the Python environment you are currently using, or the environment is not correctly configured.
fixInstall the 'natsort' package using pip: `pip install natsort`
TypeError: '<' not supported between instances of 'str' and 'int'
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.
fixEnsure 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.
natsort not sorting correctly
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).
fixReview 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.
Upgrade
Version history
8.4.0latest on PyPI · released Jun 20, 2023
Audit
Dependencies
fastnumbersoptionalOptional dependency for improved performance in string-to-number conversions.
PyICUoptionalStrongly recommended for consistent locale-aware sorting, especially on non-Windows operating systems, as Python's built-in 'locale' module can be problematic.