xplr: a hackable TUI file explorer built around Lua and external commands

What xplr actually solves for terminal users

The README is explicit that xplr is not trying to replace shell commands or GUI file managers. It calls itself an interactive orchestrator for the command-line utilities that already work with the filesystem. That framing matters, because it explains every design decision downstream: the file listing is not the product, the integration surface is.

The audience is narrow and identifiable. You already use ripgrep, fd, fzf, bat, or a preview script. You want a keyboard-driven view of a directory that can hand the selected path to any of those tools and show the result in a pane. A conventional file manager would make you leave the terminal or fight a fixed feature set. xplr instead exposes the selected file to a configuration language and lets you wire the rest.

If you only need to move files around occasionally, that flexibility is a cost, not a benefit. The README does not pretend otherwise. It positions xplr as an ideal candidate for further integration rather than a turnkey file manager, and the linked Hacks and Plugins pages on xplr.dev are where the actual value lives.

Lua configuration, messages, and the runtime model

Two dependencies in Cargo.toml tell you most of the architecture. The first is mlua with the luajit, serialize and send features enabled. The second is tui-input with serde, and ratatui (aliased as tui) with crossterm and serde. The UI is ratatui, the configuration and scripting layer is LuaJIT through mlua, and state moves between the two as serializable values.

That is the mechanism: xplr holds the file listing, selection and modes, and your Lua configuration reacts to messages and sends messages back. Because the values crossing that boundary are serializable, the same message shape can be produced by an external process, which is why the project can advertise integrations and plugins as first-class rather than as hacks bolted onto a shell wrapper.

The rest of the dependency list is a good signal of scope. There is no bundled fuzzy finder engine being written from scratch: skim is pulled in with default features disabled and an empty feature list, natord handles natural ordering, lscolors handles LS_COLORS parsing, mime_guess handles type detection, and rayon is present for parallel work. xplr is assembling proven crates rather than reimplementing them, which is consistent with the orchestrator claim. The trade-off is that the Lua API becomes the contract you depend on, and the README does not document a stability guarantee for it.

Installing xplr with cargo and running a first session

The README points to xplr.dev/en/install for installation and to the crates.io badge for the published crate. The repository also ships a flake.nix and default.nix, a snap/ directory, and a RELEASE.md that package maintainers are directed to. The most direct route for a Rust user is cargo, which builds the binary from source and therefore requires a working LuaJIT toolchain because of the mlua feature set.

cargo install xplr

After that completes, `xplr` should be on your PATH. Running it with no arguments opens the explorer on the current directory.

xplr

For a first real use, the pattern the README describes is handing the selection to a command-line utility. The documented entry points for that are the Hacks page and the Plugins page on xplr.dev, which is where the concrete Lua snippets live. The README itself gives no inline configuration example, so treat xplr.dev as required reading rather than optional documentation. A reasonable first session is: open xplr in a directory you know well, confirm the listing renders, then locate the configuration file path in the documentation and add one binding that shells out to a tool you already use.

Where xplr is the wrong tool

The README states plainly that xplr is not meant to be a replacement for standard shell commands or GUI file managers. Take that seriously. If your task is copying a folder of photos on a desktop, a GUI is faster and xplr will not help.

The more interesting failure mode is configuration drift. Because the behaviour you actually experience comes from Lua you write or copy, a fresh install is close to bare. The repository layout includes a docs/ directory and an examples/ directory with a single file, examples/run.rs, but the README does not document rollback, a migration path between configuration versions, or a compatibility policy for the Lua API. xplr has shipped v1.0.1, v1.1.0 and v1.1.1 across roughly a year, and the README is silent on whether a configuration written against one of those will load unchanged in the next.

There is also a build cost. mlua with luajit is not a pure-Rust dependency, so environments that cannot link LuaJIT, or that pin to a musl target without the right toolchain, will fail at build time rather than at runtime. The README does not walk through those cases, and the install page is where you would have to look.

xplr compared with orthodox terminal file managers

The obvious comparison is Midnight Commander, the long-standing two-panel terminal file manager. The difference is not cosmetic. Midnight Commander is an application: it ships a fixed set of operations, its own editor and viewer, and a menu system you learn once. xplr is closer to a framework. It gives you a listing and an event loop, and the operations come from the commands you bind.

That means Midnight Commander wins on day one and xplr wins on day thirty, if you invest the thirty days. If you never intend to write a binding, the investment never pays back and you have taken on a Lua runtime for nothing.

The other reference point in the same space is Yazi, which the related searches show people comparing against xplr and against Emacs. The architectural split is similar in spirit, a fast Rust core with a scripting layer, but the README here does not make claims about Yazi and it would be wrong to invent them. What can be said is that xplr's stated goal is orchestration of existing command-line utilities rather than being a self-contained file manager, and that the project documents its own integrations and plugins as the place where that goal is realised.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-08-25. The most recent release, v1.1.1, is dated 2026-08-15, with v1.1.0 before it on 2025-12-08 and v1.0.1 on 2025-07-05. That is a steady but unhurried cadence: three releases in about fourteen months, with the gap between v1.1.0 and v1.1.1 the longest of the three.

Upgrade cost is dominated by your own configuration, not by the binary. Cargo.lock is committed, so a build from the repository is reproducible, and the crate is published on crates.io with a version badge in the README. But the README does not describe a deprecation policy for Lua APIs, and it does not document rollback. If you maintain a large configuration, budget time for reading release notes before each upgrade rather than assuming the previous file still loads.

The licence is MIT, declared in Cargo.toml and present as LICENSE at the repository root. MIT is permissive: it allows reuse and redistribution with the copyright notice and permission notice retained. That is the extent of what the repository states. It is not legal advice, and if you are redistributing xplr inside a product you should read the LICENSE file and the licences of the dependencies yourself.

Editorial conclusion

Adopt xplr if you already live in a terminal, want a file explorer you can rewrite in Lua, and are willing to read the documentation at xplr.dev rather than expect sane defaults out of the box. Skip it if you want a file manager that works on first launch, or if you need a GUI or a two-pane orthodox layout. Before committing, verify two things: that your distribution or cargo can build mlua with the luajit feature, since that is a hard dependency in Cargo.toml, and that the configuration you copy from the Hacks page matches the xplr version you installed, because the Lua API is the part most likely to shift between releases.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. sayanarijit/xplr on GitHub