Ranger deep dive

Research question

Ranger is the most feature-complete terminal file manager but famously slow in specific scenarios. We need a precise keep/fix list before writing a single line of viexp.

Findings

Project state (Oct 2026)

Python + curses, Miller-columns UI. 17.4k stars, ~900 open issues, last tag v1.9.4 (Nov 2024), commits still trickling. Maintainers openly state they lack manpower (issue #1717).

Architecture

Config = 4 files with different merge semantics: rc.conf merges, rifle.conf replaces, scope.sh replaces (~700-line bash), commands.py merges (Python subclassing).
Preview pipeline = external scope.sh; communicates via exit codes: 0 = stdout preview, 1 = none, 2 = fixed-height text, 5 = image written to cache dir.
Plugins = Python monkeypatching with full interpreter access ("Plugins have full access to your computer!"). Ecosystem: ranger-devicons, ranger-zoxide, ranger-fzf-filter, etc.
Image protocols: w3m, ueberzug, urxvt, kitty, sixel, iterm2, terminology.

Why it is slow (root causes)

Cause	Evidence
Synchronous UI loop — directory listing + `stat` of every file run inline	issue #1173: 100k files = multi-second uninterruptible hang (open since 2018)
No async I/O anywhere; threading refactor stalled	issue #1025 literally labeled `wants-async`
`statvfs` on every status-bar refresh → 4–10 s j/k lag on sshfs/NFS/CryFS/s3fs	issue #1025; vifm stays fast in identical setups
Python interpreter startup ~1 s cold	issue #1717
Every preview spawns scope.sh + a chain of external binaries	architecture

Pain points (user-verified)

ueberzug unmaintained and X11-only; ueberzugpp fixes exist but are bolted on (ranger #3188, #3158, #2995; ueberzugpp #122 fractional-scaling bug on Sway/Hyprland).
Network mounts unusable without manual setlocal hacks or F (freeze_files).
:flat broken past ~30k files (#379).
No built-in trash — ArchWiki documents map DD shell gio trash as the workaround.
Config fragmentation: four files, four formats, four merge behaviors.

What users love (must keep)

Vim keys, Miller columns, :bulkrename via $EDITOR (the killer feature), rifle-style ordered opener menu (r), preview breadth (20+ types), tabs/bookmarks/marks, :filter, --choosefile/--choosedir + cd-on-exit, per-path options (setlocal).

Keep / Fix table

Keep	Fix
Miller 3-pane layout, vim key vocabulary	Native binary startup (no interpreter)
`:bulkrename` via `$EDITOR`	Async dir loading / stat / preview — UI never blocks
Rifle-style opener rules + chooser menu	No `statvfs` per frame; poll with timeout+backoff
Exit-code preview contract (scope.sh idea)	First-class trash (`gio trash`-compatible) + undo
Preview breadth with caching	Native kitty/sixel/ueberzug++ graphics, Wayland-safe
`setlocal` per-path options	One config format (TOML) with documented merge semantics
`--choosefile/--choosedir`, cd-on-exit	Virtual scrolling for 100k+ entry dirs
`F` freeze escape hatch	Automatic freeze on network/fuse mounts

Outcome

Direct input to decisions/ADR-002-extension-architecture (extension model), ADR-004 (preview protocols) and the roadmap's async requirements (Sprint 8).

Sources

https://github.com/ranger/ranger — README, wiki, examples/plugins
https://wiki.archlinux.org/title/Ranger
Issues: #1717 (startup), #1173 (100k files), #1025 (network lag), #379 (:flat), #3188 / #3158 / #2995 (ueberzug family)
https://github.com/seebye/ueberzug (unmaintained notice), https://github.com/jstkdng/ueberzugpp
Community: r/commandline "Is yazi overhyped?", r/linux FM threads, x-cmd six-FM comparison, https://mqdir.com/blog/file-management/nnn-vs-yazi

4.0 KiB Raw Blame History Unescape Escape