{"id":1000,"library":"natsort","title":"Natural Sorting for Python","description":"natsort is a Python library that provides 'natural' sorting capabilities, enabling lists containing numbers (e.g., filenames, version strings) to be sorted numerically rather than strictly lexicographically. It's a versatile tool that handles various data types and offers extensive customization. The current version is 8.4.0, and the library is actively maintained with a regular release cadence.","status":"active","version":"8.4.0","language":"python","source_language":"en","source_url":"https://github.com/SethMMorton/natsort","tags":["sorting","natural sorting","list sorting","file sorting","version sorting","alphanumeric sorting"],"install":[{"cmd":"pip install natsort","lang":"bash","label":"Install natsort"}],"dependencies":[{"reason":"Optional dependency for improved performance in string-to-number conversions.","package":"fastnumbers","optional":true},{"reason":"Strongly recommended for consistent locale-aware sorting, especially on non-Windows operating systems, as Python's built-in 'locale' module can be problematic.","package":"PyICU","optional":true}],"imports":[{"note":"The primary function for natural sorting, returns a new sorted list.","symbol":"natsorted","correct":"from natsort import natsorted"},{"note":"Used to generate a key for in-place sorting with 'list.sort()'.","symbol":"natsort_keygen","correct":"from natsort import natsort_keygen"},{"note":"Provides algorithm options (e.g., ns.FLOAT, ns.LOCALE) for advanced customization.","symbol":"ns","correct":"from natsort import ns"},{"note":"Convenience function (added in v7.1.0) to sort paths like a file browser.","symbol":"os_sorted","correct":"from natsort import os_sorted"},{"note":"Convenience function for locale-aware sorting (equivalent to natsorted with alg=ns.LOCALE).","symbol":"humansorted","correct":"from natsort import humansorted"},{"note":"Convenience function for sorting by real numbers (equivalent to natsorted with alg=ns.REAL).","symbol":"realsorted","correct":"from natsort import realsorted"}],"quickstart":{"code":"from natsort import natsorted\n\nunsorted_list = ['file1.txt', 'file10.txt', 'file2.txt', 'file_2.jpeg', 'file_1.png', 'file_10.gif']\nsorted_list = natsorted(unsorted_list)\n\nprint(sorted_list)\n# Expected output: ['file_1.png', 'file1.txt', 'file_2.jpeg', 'file2.txt', 'file_10.gif', 'file10.txt']","lang":"python","description":"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()`."},"warnings":[{"fix":"If 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.","message":"The 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.","severity":"breaking","affected_versions":"<4.0.0 to >=4.0.0"},{"fix":"Ensure your environment and tooling are compatible with type-hinted code. Most users will not experience issues.","message":"Version 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.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"To sort in-place, either reassign: `my_list = natsorted(my_list)` or use `my_list.sort(key=natsort_keygen())`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `PyICU` (`pip install PyICU`) to ensure robust locale-sensitive sorting behavior across different operating systems.","message":"For 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Convert byte strings to regular Python strings (e.g., using `.decode('utf-8')`) before passing them to `natsorted()` or related functions.","message":"`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.","severity":"gotcha","affected_versions":"Python 3, all versions"}],"env_vars":null,"last_verified":"2026-05-12T22:28:53.947Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Install the 'natsort' package using pip: `pip install natsort`","cause":"The 'natsort' package is not installed in the Python environment you are currently using, or the environment is not correctly configured.","error":"ModuleNotFoundError: No module named 'natsort'"},{"fix":"Ensure 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.","cause":"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.","error":"TypeError: '<' not supported between instances of 'str' and 'int'"},{"fix":"Review 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.","cause":"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).","error":"natsort not sorting correctly"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"8.4.0","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"8.4.0","pypi_latest":"8.4.0","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"natsort","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.09,"mem_mb":2.7,"disk_size":"18.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"natsort","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":2.7,"disk_size":"18.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"natsort","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.4,"import_time_s":0.05,"mem_mb":2.7,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"natsort","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.7,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"natsort","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.15,"mem_mb":2.5,"disk_size":"19.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"natsort","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":2.5,"disk_size":"19.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"natsort","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.6,"import_time_s":0.14,"mem_mb":2.5,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"natsort","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":2.5,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"natsort","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.11,"mem_mb":2.2,"disk_size":"11.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"natsort","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":2.2,"disk_size":"11.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"natsort","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.4,"import_time_s":0.12,"mem_mb":2.2,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"natsort","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":2.2,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"natsort","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.1,"mem_mb":2.1,"disk_size":"11.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"natsort","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.11,"mem_mb":2.1,"disk_size":"11.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"natsort","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.4,"import_time_s":0.11,"mem_mb":1.9,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"natsort","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":1.9,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"natsort","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.08,"mem_mb":2.6,"disk_size":"17.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"natsort","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":2.6,"disk_size":"17.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"natsort","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.7,"import_time_s":0.06,"mem_mb":2.6,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"natsort","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.6,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}