{"id":3269,"library":"scandir","title":"scandir, a better directory iterator","description":"scandir is a Python library that provides a faster directory iterator and a faster `os.walk()` implementation than the standard library's `os.listdir()` and `os.walk()` for older Python versions. It backported the functionality that was later added to Python 3.5 as `os.scandir`. The current version is 1.10.0, with releases occurring infrequently as new Python versions are supported or critical fixes are needed.","status":"active","version":"1.10.0","language":"en","source_language":"en","source_url":"https://github.com/benhoyt/scandir","tags":["filesystem","directory","os","performance","backport","walk"],"install":[{"cmd":"pip install scandir","lang":"bash","label":"Install `scandir`"}],"dependencies":[],"imports":[{"note":"The `scandir` library provides its own `scandir` function. For Python 3.5+, the built-in `os.scandir` is generally preferred.","wrong":"from os import scandir","symbol":"scandir","correct":"from scandir import scandir"},{"note":"The `scandir` library offers a faster `walk` function using its `scandir` functionality. For Python 3.5+, the built-in `os.walk` is often sufficient.","wrong":"from os import walk","symbol":"walk","correct":"from scandir import walk"},{"note":"Exposed in v1.7. Represents an entry in a directory scan, providing access to name, path, and file type information.","symbol":"DirEntry","correct":"from scandir import DirEntry"}],"quickstart":{"code":"import scandir\nimport os\n\ndef list_dir_contents(path):\n    try:\n        print(f\"Listing contents of: {path}\")\n        for entry in scandir.scandir(path):\n            if entry.is_file():\n                print(f\"  File: {entry.name}\")\n            elif entry.is_dir():\n                print(f\"  Dir: {entry.name}/\")\n            elif entry.is_symlink():\n                print(f\"  Symlink: {entry.name} -> {entry.path}\")\n    except FileNotFoundError:\n        print(f\"Error: Directory not found at {path}\")\n    except PermissionError:\n        print(f\"Error: Permission denied for {path}\")\n\n# Example usage: list current directory\nlist_dir_contents('.')\n\n# Example usage: walk a directory tree\nprint('\\nWalking directory tree:')\nfor root, dirs, files in scandir.walk('.'):\n    level = root.count(os.sep)\n    indent = ' ' * 4 * level\n    print(f'{indent}{os.path.basename(root)}/')\n    subindent = ' ' * 4 * (level + 1)\n    for d in dirs:\n        print(f'{subindent}Dir: {d}/')\n    for f in files:\n        print(f'{subindent}File: {f}')\n","lang":"python","description":"This quickstart demonstrates how to use `scandir.scandir()` to iterate over directory entries efficiently and `scandir.walk()` for a faster directory tree traversal, similar to `os.walk()`."},"warnings":[{"fix":"Upgrade to Python 3.4+ or Python 2.7 if using older `scandir` versions, or pin `scandir<1.10.0` for Python 2.6/3.x < 3.4 environments.","message":"Version 1.10.0 removed support for Python 2.6 and Python 3 versions less than 3.4.","severity":"breaking","affected_versions":">=1.10.0"},{"fix":"For Python 3.5+, prefer `import os` and use `os.scandir()` and `os.walk()`. Only use the `scandir` library if targeting older Python versions or if profiling shows a significant performance gain from its C extension.","message":"For Python 3.5 and newer, the functionality of `scandir` (and an optimized `os.walk`) is built into the standard `os` module (`os.scandir`, `os.walk`). It's generally recommended to use the built-in functions in Python 3.5+ for better compatibility and fewer external dependencies, unless specific performance needs dictate the `scandir` library's C extension.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the C extension is successfully built during installation if maximum performance is critical. Check installation logs for C extension build warnings.","message":"The C extension is optional as of v1.8. If the C extension fails to build or is unavailable (e.g., on specific platforms like Jython), a slower pure-Python fallback will be used. This can lead to unexpected performance degradation if the C extension is assumed.","severity":"gotcha","affected_versions":">=1.8"},{"fix":"Review code that uses `st_atime`, `st_mtime`, `st_ctime` from `DirEntry.stat()` to ensure it handles float values correctly. Cast to `int` if integer timestamps are strictly required.","message":"The type of `entry.stat().st_Xtime` (e.g., `st_atime`, `st_mtime`) changed from `int` to `float` in version 1.4 to better mimic `os.stat` behavior. Code relying on integer timestamps might need adjustment.","severity":"gotcha","affected_versions":">=1.4"},{"fix":"Ensure you are on the latest `scandir` version. If problems persist, thoroughly test unicode path handling on your target OS and Python version, paying close attention to file system encoding settings.","message":"Historically, unicode handling on Python 2.x and specific operating systems (Windows, Linux, OpenBSD, Solaris) has had several fixes across versions (v1.2, v1.3, v1.6, v1.10.0). While most common issues are resolved, users on unusual setups or older `scandir` versions might still encounter path encoding issues.","severity":"gotcha","affected_versions":"<1.10.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}