scandir

library1.10.0pypypi✓ verified 23d ago

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.

database

pip install scandir

github ↗package ↗

INSTALL

IMPORT

SIG · SCANDIR

scandir

databasepythonv1.10.0

Install

2.5s avg

Import

45ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.10.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.044s · 19.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.5s · import 0.046s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

scandir

✓ from scandir import scandir

✗ from os import scandir

The `scandir` library provides its own `scandir` function. For Python 3.5+, the built-in `os.scandir` is generally preferred.

walk

✓ from scandir import walk

✗ from os import walk

The `scandir` library offers a faster `walk` function using its `scandir` functionality. For Python 3.5+, the built-in `os.walk` is often sufficient.

DirEntry

✓ from scandir import DirEntry

Exposed in v1.7. Represents an entry in a directory scan, providing access to name, path, and file type information.

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()`.

import scandir import os def list_dir_contents(path): try: print(f"Listing contents of: {path}") for entry in scandir.scandir(path): if entry.is_file(): print(f" File: {entry.name}") elif entry.is_dir(): print(f" Dir: {entry.name}/") elif entry.is_symlink(): print(f" Symlink: {entry.name} -> {entry.path}") except FileNotFoundError: print(f"Error: Directory not found at {path}") except PermissionError: print(f"Error: Permission denied for {path}") # Example usage: list current directory list_dir_contents('.') # Example usage: walk a directory tree print('\nWalking directory tree:') for root, dirs, files in scandir.walk('.'): level = root.count(os.sep) indent = ' ' * 4 * level print(f'{indent}{os.path.basename(root)}/') subindent = ' ' * 4 * (level + 1) for d in dirs: print(f'{subindent}Dir: {d}/') for f in files: print(f'{subindent}File: {f}')

Debug

Known issues

breakingVersion 1.10.0 removed support for Python 2.6 and Python 3 versions less than 3.4.

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.

affects: >=1.10.0

gotchaFor 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.

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.

affects: All versions

gotchaThe 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.

fix

Ensure the C extension is successfully built during installation if maximum performance is critical. Check installation logs for C extension build warnings.

affects: >=1.8

gotchaThe 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.

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.

affects: >=1.4

gotchaHistorically, 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.

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.

affects: <1.10.0

Upgrade

Version history

1.10.0latest on PyPI · released Mar 9, 2019

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node