2. Examples and Recipes

If you want more detailed examples than given on this page, please see https://github.com/SethMMorton/natsort/tree/master/test_natsort.

2.1. Basic Usage

In the most basic use case, simply import natsorted() and use it as you would sorted():

>>> a = ['a50', 'a51.', 'a50.4', 'a5.034e1', 'a50.300']
>>> sorted(a)
['a5.034e1', 'a50', 'a50.300', 'a50.4', 'a51.']
>>> from natsort import natsorted, ns
>>> natsorted(a)
['a50', 'a50.300', 'a5.034e1', 'a50.4', 'a51.']

2.2. Sort Version Numbers

With default options, natsorted() will not sort version numbers well. Version numbers are best sorted by searching for valid unsigned int literals, not floats. This can be achieved in three ways, as shown below:

>>> a = ['ver-2.9.9a', 'ver-1.11', 'ver-2.9.9b', 'ver-1.11.4', 'ver-1.10.1']
>>> natsorted(a)  # This gives incorrect results
['ver-2.9.9a', 'ver-2.9.9b', 'ver-1.11', 'ver-1.11.4', 'ver-1.10.1']
>>> natsorted(a, alg=ns.INT | ns.UNSIGNED)
['ver-1.10.1', 'ver-1.11', 'ver-1.11.4', 'ver-2.9.9a', 'ver-2.9.9b']
>>> natsorted(a, alg=ns.VERSION)
['ver-1.10.1', 'ver-1.11', 'ver-1.11.4', 'ver-2.9.9a', 'ver-2.9.9b']
>>> from natsort import versorted
>>> versorted(a)
['ver-1.10.1', 'ver-1.11', 'ver-1.11.4', 'ver-2.9.9a', 'ver-2.9.9b']

You can see that alg=ns.VERSION is a shortcut for alg=ns.INT | ns.UNSIGNED, and the versorted() is a shortcut for natsorted(alg=ns.VERSION). The recommend manner to sort version numbers is to use versorted().

2.2.1. Sorting with Alpha, Beta, and Release Candidates

By default, if you wish to sort versions with a non-strict versioning scheme, you may not get the results you expect:

>>> a = ['1.2', '1.2rc1', '1.2beta2', '1.2beta1', '1.2alpha', '1.2.1', '1.1', '1.3']
>>> versorted(a)
['1.1', '1.2', '1.2.1', '1.2alpha', '1.2beta1', '1.2beta2', '1.2rc1', '1.3']

To make the ‘1.2’ pre-releases come before ‘1.2.1’, you need to use the following recipe:

>>> versorted(a, key=lambda x: x.replace('.', '~'))
['1.1', '1.2', '1.2alpha', '1.2beta1', '1.2beta2', '1.2rc1', '1.2.1', '1.3']

If you also want ‘1.2’ after all the alpha, beta, and rc candidates, you can modify the above recipe:

>>> versorted(a, key=lambda x: x.replace('.', '~')+'z')
['1.1', '1.2alpha', '1.2beta1', '1.2beta2', '1.2rc1', '1.2', '1.2.1', '1.3']

Please see this issue to see why this works.

2.3. Sort OS-Generated Paths

In some cases when sorting file paths with OS-Generated names, the default natsorted algorithm may not be sufficient. In cases like these, you may need to use the ns.PATH option:

>>> a = ['./folder/file (1).txt',
...      './folder/file.txt',
...      './folder (1)/file.txt',
...      './folder (10)/file.txt']
>>> natsorted(a)
['./folder (1)/file.txt', './folder (10)/file.txt', './folder/file (1).txt', './folder/file.txt']
>>> natsorted(a, alg=ns.PATH)
['./folder/file.txt', './folder/file (1).txt', './folder (1)/file.txt', './folder (10)/file.txt']

2.4. Locale-Aware Sorting (Human Sorting)

You can instruct natsort to use locale-aware sorting with the ns.LOCALE option. In addition to making this understand non-ASCII characters, it will also properly interpret non-‘.’ decimal separators and also properly order case. It may be more convenient to just use the humansorted() function:

>>> from natsort import humansorted
>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'en_US.UTF-8')
'en_US.UTF-8'
>>> a = ['Apple', 'corn', 'Corn', 'Banana', 'apple', 'banana']
>>> natsorted(a, alg=ns.LOCALE)
['apple', 'Apple', 'banana', 'Banana', 'corn', 'Corn']
>>> humansorted(a)
['apple', 'Apple', 'banana', 'Banana', 'corn', 'Corn']

You may find that if you do not explicitly set the locale your results may not be as you expect... I have found that it depends on the system you are on. If you use PyICU (see below) then you should not need to do this.

2.4.1. A Note For Bugs With Locale-Aware Sorting

If you find that ns.LOCALE (or humansorted()) does not give the results you expect, before filing a bug report please try to first install PyICU. There are some known bugs with the locale module from the standard library that are solved when using PyICU.

2.5. Controlling Case When Sorting

For non-numbers, by default natsort used ordinal sorting (i.e. it sorts by the character’s value in the ASCII table). For example:

>>> a = ['Apple', 'corn', 'Corn', 'Banana', 'apple', 'banana']
>>> natsorted(a)
['Apple', 'Banana', 'Corn', 'apple', 'banana', 'corn']

There are times when you wish to ignore the case when sorting, you can easily do this with the ns.IGNORECASE option:

>>> natsorted(a, alg=ns.IGNORECASE)
['Apple', 'apple', 'Banana', 'banana', 'corn', 'Corn']

Note thats since Python’s sorting is stable, the order of equivalent elements after lowering the case is the same order they appear in the original list.

Upper-case letters appear first in the ASCII table, but many natural sorting methods place lower-case first. To do this, use ns.LOWERCASEFIRST:

>>> natsorted(a, alg=ns.LOWERCASEFIRST)
['apple', 'banana', 'corn', 'Apple', 'Banana', 'Corn']

It may be undesirable to have the upper-case letters grouped together and the lower-case letters grouped together; most would expect all “a”s to bet together regardless of case, and all “b”s, and so on. To achieve this, use ns.GROUPLETTERS:

>>> natsorted(a, alg=ns.GROUPLETTERS)
['Apple', 'apple', 'Banana', 'banana', 'Corn', 'corn']

You might combine this with ns.LOWERCASEFIRST to get what most would expect to be “natural” sorting:

>>> natsorted(a, alg=ns.G | ns.LF)
['apple', 'Apple', 'banana', 'Banana', 'corn', 'Corn']

2.6. Customizing Float Definition

By default natsorted() searches for any float that would be a valid Python float literal, such as 5, 0.4, -4.78, +4.2E-34, etc. Perhaps you don’t want to search for signed numbers, or you don’t want to search for exponential notation, the ns.UNSIGNED and ns.NOEXP options allow you to do this:

>>> a = ['a50', 'a51.', 'a+50.4', 'a5.034e1', 'a+50.300']
>>> natsorted(a)
['a50', 'a+50.300', 'a5.034e1', 'a+50.4', 'a51.']
>>> natsorted(a, alg=ns.UNSIGNED)
['a50', 'a5.034e1', 'a51.', 'a+50.300', 'a+50.4']
>>> natsorted(a, alg=ns.NOEXP)
['a5.034e1', 'a50', 'a+50.300', 'a+50.4', 'a51.']

2.7. Using a Custom Sorting Key

Like the built-in sorted function, natsorted can accept a custom sort key so that:

>>> from operator import attrgetter, itemgetter
>>> a = [['a', 'num4'], ['b', 'num8'], ['c', 'num2']]
>>> natsorted(a, key=itemgetter(1))
[['c', 'num2'], ['a', 'num4'], ['b', 'num8']]
>>> class Foo:
...    def __init__(self, bar):
...        self.bar = bar
...    def __repr__(self):
...        return "Foo('{0}')".format(self.bar)
>>> b = [Foo('num3'), Foo('num5'), Foo('num2')]
>>> natsorted(b, key=attrgetter('bar'))
[Foo('num2'), Foo('num3'), Foo('num5')]

2.8. Generating a Natsort Key

If you need to sort a list in-place, you cannot use natsorted(); you need to pass a key to the list.sort() method. The function natsort_keygen() is a convenient way to generate these keys for you:

>>> from natsort import natsort_keygen
>>> a = ['a50', 'a51.', 'a50.4', 'a5.034e1', 'a50.300']
>>> natsort_key = natsort_keygen()
>>> a.sort(key=natsort_key)
>>> a
['a50', 'a50.300', 'a5.034e1', 'a50.4', 'a51.']
>>> versort_key = natsort_keygen(alg=ns.VERSION)
>>> a = ['ver-2.9.9a', 'ver-1.11', 'ver-2.9.9b', 'ver-1.11.4', 'ver-1.10.1']
>>> a.sort(key=versort_key)
>>> a
['ver-1.10.1', 'ver-1.11', 'ver-1.11.4', 'ver-2.9.9a', 'ver-2.9.9b']

natsort_keygen() has the same API as natsorted() (minus the reverse option).

2.9. Sorting Multiple Lists According to a Single List

Sometimes you have multiple lists, and you want to sort one of those lists and reorder the other lists according to how the first was sorted. To achieve this you would use the index_natsorted() or index_versorted() in combination with the convenience function order_by_index():

>>> from natsort import index_natsorted, order_by_index
>>> a = ['a2', 'a9', 'a1', 'a4', 'a10']
>>> b = [4,    5,    6,    7,    8]
>>> c = ['hi', 'lo', 'ah', 'do', 'up']
>>> index = index_natsorted(a)
>>> order_by_index(a, index)
['a1', 'a2', 'a4', 'a9', 'a10']
>>> order_by_index(b, index)
[6, 4, 7, 5, 8]
>>> order_by_index(c, index)
['ah', 'hi', 'do', 'lo', 'up']

2.10. Returning Results in Reverse Order

Just like the sorted() built-in function, you can supply the reverse option to return the results in reverse order:

>>> a = ['a2', 'a9', 'a1', 'a4', 'a10']
>>> natsorted(a, reverse=True)
['a10', 'a9', 'a4', 'a2', 'a1']