Installation & Setup

natsort is published on PyPI and requires Python 3.9 or greater.

Basic Installation

For most standard use cases, you can install the pure-Python version of natsort via pip. This version has zero external dependencies and works seamlessly across all platforms:

pip install natsort

To unlock maximum performance and the most accurate OS-level sorting rules, natsort offers two optional C-based dependencies. You can install these using the pip "extras" bracket notation.

1. fastnumbers (For Maximum Performance)

String-to-number conversion is the most CPU-intensive part of the natural sorting algorithm. By default, natsort uses Python's built-in int() and float() functions alongside localized regular expressions.

If you install the fastnumbers package (version >= 2.0.0), natsort automatically detects it and delegates these conversions to highly optimized C routines. This provides a measurable speed boost, which is crucial if you are sorting massive datasets (e.g., millions of log lines or database entries).

To install:

pip install natsort[fast]

Note: natsort will gracefully fall back to its internal pure-Python implementation if fastnumbers is not found, so your code will never break if a target environment lacks a C compiler.

2. PyICU (For Locale & Cross-Platform OS Sorting)

Python's built-in locale module is notoriously inconsistent across different operating systems (especially on macOS and certain BSD derivatives). If you intend to use natsort's "Human Sorting" capabilities (humansorted(), ns.LOCALE) or the native OS path sorting (os_sorted()), PyICU is strongly recommended.

PyICU provides bindings to the International Components for Unicode (ICU) C++ library. It guarantees perfect, cross-platform parsing of special characters, localized thousands separators (e.g., , vs .), and decimal separators.

To install:

pip install natsort[icu]

Troubleshooting PyICU Installation on Linux

Because PyICU relies on the ICU C++ library, installing it via pip on Linux requires the ICU development headers to be present on your system. If the pip install command fails with compilation errors, install the headers first:

Debian/Ubuntu: 

sudo apt-get update
sudo apt-get install libicu-dev
pip install natsort[icu]

Fedora/RHEL: 

sudo dnf install libicu-devel
pip install natsort[icu]

Installing the Full Suite

To install natsort with both fastnumbers and PyICU enabled, use a comma-separated list:

pip install natsort[fast,icu]

Verifying Installation

To verify that natsort is installed correctly and check its version, you can invoke the CLI module from your terminal:

python -m natsort --version

If you are writing a library that depends on natsort, it is generally safe to depend strictly on "natsort", leaving the decision to install the [fast] or [icu] extras up to the end-user of your application.