scandir vs listdir vs iterdir: Localhost Lab

Intro — what this post promises

Listing a directory: os.scandir, os.listdir, or pathlib.Path.iterdir? This lab measures entries/s on a synthetic tree (flat + nested) on Linux localhost, then shows why DirEntry.is_file() beats listdir + os.path.isfile.

It is not a remake of the glob vs rglob vs walk localhost lab (pattern matching / recursive globs). Here the question is directory iterator APIs and when cached DirEntry metadata wins.

Related links:

• glob vs rglob vs walk localhost lab
• mmap vs read scan localhost lab
• bytesio vs spooled tempfile localhost lab
• shutil copyfile vs manual localhost lab
• pathlib vs ospath localhost lab
• tarfile vs zipfile localhost lab
• secrets vs urandom localhost lab
• textwrap fill vs manual localhost lab

Lab honesty (1 Oct 2026 IST): Python 3.13.5. Fixtures under lab-evidence/90-scandir-vs-listdir/results/fixture_tree/. Affiliates: 0. No Docker.

Verdict up front (2000 entries, is_file path): scandir ~3056.2 k/s vs listdir+isfile ~353.7 k/s (~8.64×) vs Path.iterdir().is_file ~242.4 k/s. For names only at 8000 files, listdir ~4288.1 k/s edged scandir ~3279.9 k/s; iterdir ~1079.8 k/s.

Arms

Lab topology

flat: 500 / 2000 / 8000 files · 7 rounds · p50
isfile check at n=2000
nested: 50 dirs × 40 files (2050 entries)
metric: entries/s

Script: lab-evidence/90-scandir-vs-listdir/results/run_lab.py.

Lead table — flat names (p50 entries/s)

When you need is_file (n=2000)

~8.64× — this is the scandir headline. Extra stat per name is the tax DirEntry avoids when the type is already known from the directory read.

Nested walk (2050 entries)

Reading it

• Names only: listdir is fine (and slightly fastest here).
• Need type/stat: prefer scandir / DirEntry.
• Path.iterdir is ergonomic; expect a measurable object-creation tax on huge directories.
• Use os.walk or a scandir stack for trees; rglob("*") was ~4.45× slower on this nest.

Names-only vs metadata

If you only print names, listdir avoids building DirEntry objects and won slightly here. The moment you call isfile/isdir/stat on each name, you pay syscalls that scandir often already satisfied. Rule of thumb from this box: branching on type → scandir; names dump → listdir is acceptable.

pathlib tax

Path.iterdir returns Path objects — great for chaining .suffix / .with_name. On an 8000-file directory that object churn showed up as ~4.0× slower than raw listdir. Use pathlib at the edges; tight loops may want scandir/listdir.

Pitfalls

• Calling os.path.isfile on every listdir name in a hot path.
• Assuming scandir is always fastest for names-only (not on this box).
• Forgetting with os.scandir(...) (resource lifetime).
• Following symlinks unintentionally in recursive walks.

Reproduce

python3 lab-evidence/90-scandir-vs-listdir/results/run_lab.py

Evidence: summary.json, fixture_tree/.

Limits

One Linux box, synthetic files on local FS. Not networked filesystems / huge directories with millions of entries. Cold-cache dentries may differ.

Takeaway

For name listing, listdir ~4288.1 k/s ≈ scandir ~3279.9 k/s at 8000 files. For is_file filtering, scandir ~8.64× beat listdir+stat. Default to scandir when you branch on file type; keep listdir for simple name dumps.