natsort

You can combine multiple sorting algorithms and modifiers using the bitwise OR operator (|) with the ns enum. The ns enum provides both long names (e.g., ns.LOCALE) and short forms (e.g., ns.L).

Available modifiers include:

• ns.REAL / ns.R (Signed floats)
• ns.LOCALE / ns.L (Locale-aware)
• ns.IGNORECASE / ns.IC (Case-insensitive)

from natsort import natsorted, ns

a = ['Apple', 'apple15', 'Banana', 'apple14,689', 'banana']

# Combine multiple modifiers
natsorted(a, alg=ns.REAL | ns.LOCALE | ns.IGNORECASE)

# Using short forms
natsorted(a, alg=ns.R | ns.L | ns.IC)

The natsort library provides a key function that can be passed to standard Python sorting methods like list.sort() or sorted(). This key is generated using natsort_keygen().

natsorted() is essentially a wrapper that uses this key generator. The key returned by natsort_keygen() always returns a tuple by attempting to split strings into numbers (converted to int or float) and non-numbers, or recursively applying the key to sequences.

from natsort import natsort_keygen

natsort_key = natsort_keygen()
sorted_list = sorted(['1', '10', '2'], key=natsort_key)
# Result: ['1', '2', '10']

If you are experiencing unexpected sorting results, the best way to debug is to generate the sort key manually using natsort_keygen() with the same options used in your natsorted() call. This allows you to inspect exactly how the input data is being transformed into the comparison tuple.

from natsort import natsort_keygen

# Use the same options you passed to natsorted()
key_func = natsort_keygen(alg='...') 

# Inspect the key for a problematic item
print(key_func('problematic_item'))

Install the core library using pip. Note that natsort requires Python 3.9 or greater.

pip install natsort

You can install optional dependencies using the extras notation at installation time:

• Use fast to install fastnumbers (version >=2.0.0), which improves efficiency for string-to-number conversions.
• Use icu to install PyICU, which is recommended for locale-dependent sorting.

To install both:

pip install natsort[fast,icu]

To install only fastnumbers:

pip install natsort[fast]

The ns enum (an IntEnum) is used to control the natsort algorithm via the alg parameter in natsort functions. You can combine multiple options simultaneously using the bitwise OR operator (|).

For example, to use integer parsing, path awareness, and locale awareness, you would use ns.INT | ns.PATH | ns.LOCALE.

import natsort as ns
a = ["num5.10", "num-3", "num5.3", "num2"]
# Using the REAL shortcut (FLOAT | SIGNED)
sorted_list = ns.natsorted(a, alg=ns.REAL)

The ns object (an instance of NSType) provides access to various sorting type constants. For convenience, these members are also exported directly into the natsort package namespace.

from natsort import ns, NSType

# You can use the ns namespace
# or the direct exports provided by the package

Several APIs were removed in version 6.0.0. To identify if your code is using deprecated features, run your script with the DeprecationWarning flag enabled:

python -Wdefault::DeprecationWarning my-code.py

Alternatively, set the PYTHONWARNINGS environment variable:

export PYTHONWARNINGS="default::DeprecationWarning"
python my-code.py

Removed in 6.0.0:

• number_type keyword argument
• signed keyword argument
• exp keyword argument
• as_path keyword argument
• py3_safe keyword argument
• ns.TYPESAFE
• ns.DIGIT
• ns.VERSION
• versorted()
• index_versorted()

Unlike the built-in sorted() function, which raises a TypeError when comparing incompatible types like int and str, natsorted() can handle lists containing a mix of int, float, and str types.

from natsort import natsorted

a = ['4.5', 6, 2.0, '5', 'a']
natsorted(a)
# Output: [2.0, '4.5', '5', 6, 'a']

While natsort does not explicitly parse versioning logic, most common versioning schemes (like MAJOR.MINOR, MAJOR.MINOR.PATCH, or YEAR.MONTH.DAY) work out-of-the-box with natsorted() because they follow natural numeric patterns.

from natsort import natsorted

a = ['version-1.9', 'version-2.0', 'version-1.11', 'version-1.10']
natsorted(a)
# Output: ['version-1.9', 'version-1.10', 'version-1.11', 'version-2.0']

The natsort library does not natively support bytes for sorting to avoid conversion errors. Instead, use these utility functions to decode bytes to str before sorting:

• decoder()
• as_ascii()
• as_utf8()