Command-Line Interface

natsort comes packaged with a powerful command-line script. This allows you to natively and naturally sort text outputs, file lists, or log files directly in your terminal without needing to write a Python script.

Basic Usage

You can invoke the CLI directly by running the natsort command or via python -m natsort.

Sorting Arguments Directly

Pass space-separated strings directly to the command:

$ natsort "item-10" "item-2" "item-1"
item-1
item-2
item-10

Piping from Standard Input (stdin)

The true power of the CLI is piping the output of other terminal commands (like cat, ls, or find) directly into natsort.

# Sort lines from a text file
$ cat items.txt | natsort

# Sort a directory listing naturally
$ ls -1 | natsort

Advanced Workflows

Sorting File Paths Contextually

If you are sorting file paths that contain parenthesis, extensions, or subdirectories, use the -p (--paths) flag. This ensures paths are parsed hierarchically (mimicking ns.PATH).

$ natsort --paths "folder/" "folder (1)/" "folder (2)/"
folder/
folder (1)/
folder (2)/

Filtering by Numerical Ranges

natsort can extract numbers from your text and act as a filter. Use the -f (--filter) flag to supply a LOW and HIGH range. Only lines containing a number within that range will be output.

For example, if you have a list of server logs (server-1.log, server-2.log, etc.), and you only want logs 10 through 20:

$ cat logs.txt | natsort --filter 10 20
server-10.log
server-11.log
...
server-20.log

Conversely, -F (--reverse-filter) excludes items in that range, and -e (--exclude) omits specific exact numbers.

Handling find and Zero-Terminated Strings

When dealing with file paths containing spaces or weird characters, standard bash tools use \0 (null bytes) instead of newlines. natsort supports this via the -z (--zero-terminated) flag.

# Safely find, sort naturally, and pass to xargs
$ find . -name "*.txt" -print0 | natsort -z | xargs -0 cat

Full Options Reference

usage: natsort [-h] [--version] [-p] [-f LOW HIGH] [-F LOW HIGH] [-e EXCLUDE]
               [-r] [-t {int,float,real,f,i,r}] [--nosign] [-s] [--noexp] [-l]
               [-z]
               [entries ...]

Perform a natural sort on entries given on the command-line.

positional arguments:
  entries               The entries to sort. Taken from stdin if nothing is given
                        on the command line.

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -p, --paths           Interpret the input as file paths. Needed to accurately sort
                        OS-generated paths like "Folder/" and "Folder (1)/
".
  -f LOW HIGH, --filter LOW HIGH
                        Keep only entries that have a number falling in the given range.
  -F LOW HIGH, --reverse-filter LOW HIGH
                        Exclude entries that have a number falling in the given range.
  -e EXCLUDE, --exclude EXCLUDE
                        Exclude an entry that contains a specific number.
  -r, --reverse         Returns in reversed order.
  -t {int,float,real,f,i,r}, --number-type {int,float,real,f,i,r}
                        Choose the type of number to search for:
                        "int": integers (default).
                        "float": floating-point numbers.
                        "real": shortcut for "float" with --sign.
  --nosign              Do not consider "+" or "-" as part of a number (default).
  -s, --sign            Consider "+" or "-" as part of a number.
  --noexp               Do not consider an exponential as part of a number (e.g. 1e4).
  -l, --locale          Use locale-aware sorting (requires PyICU for best results).
  -z, --zero-terminated When reading from stdin, split entries on nulls (\\0) instead
                        of newlines.