# joshuto: a ranger-like terminal file manager in Rust

> joshuto is a TUI file manager inspired by ranger, written in Rust and configured through TOML files. It installs from crates.io, Homebrew or a pre-compiled binary script, and it expects you to bring your own ranger muscle memory.

**kamiyaa/joshuto** — ranger-like terminal file manager written in Rust

- Repository: https://github.com/kamiyaa/joshuto
- Website: https://crates.io/crates/joshuto
- Stars: 3,732 · Forks: 165
- Language: Rust
- License: LGPL-3.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/kamiyaa-joshuto

## What joshuto replaces, and for whom

joshuto is a terminal file manager modeled on ranger. The README describes it as a 'ranger-like terminal file manager written in Rust', and the Cargo.toml description says 'Terminal file manager inspired by ranger'. That framing matters: this is not a general-purpose file browser for people who are uncomfortable in a terminal. It is for engineers who already live in a shell, already know ranger or lf or nnn, and want the same three-pane, keyboard-driven workflow with a different implementation underneath.

The problem it addresses is specific. A shell plus coreutils is fine for moving one file, but it gets awkward when you are comparing two directory trees, previewing images before moving them, or running a batch rename across forty files. joshuto keeps the directory listing, the preview pane and the parent-directory context on screen at once, and maps every action to a keystroke. The README's navigation table is a compact statement of intent: arrow keys or h/j/k/l to move, l to open, h to go up. If that mapping is already in your fingers from vim or ranger, the learning cost is near zero. If it is not, joshuto will feel like a wall of undocumented keys before it feels useful.

## How joshuto is put together

The dependency list in Cargo.toml is the clearest description of the architecture. joshuto renders through ratatui with the termion backend, and ratatui-image handles image previews. File watching uses notify, so the directory listing can refresh when something else changes the filesystem. File operations run asynchronously: the README lists 'Asynch File IO (cut/copy/paste)' as a feature, which is why a large copy does not freeze the interface, and why there is a task view bound to w.

Configuration is split across five TOML files, all with examples in the repository's config/ directory: joshuto.toml for general settings, keymap.toml for keybindings, mimetype.toml for mapping file types to applications, theme.toml for colors, and bookmarks.toml for bookmarks. That separation is deliberate and useful. You can rewrite every keybinding without touching your color scheme, and you can change which program opens a PDF without touching either.

Several dependencies are optional at the feature level. The default feature set enables devicons and syntax_highlight, where syntax_highlight pulls in ansi-to-tui. A file_mimetype feature exists as well. Clipboard support is not a Rust crate at all; the README lists xsel, xclip or wl-clipboard as optional external dependencies, which means joshuto shells out for clipboard operations rather than linking a library. fzf and zoxide are also listed as optional, and the README credits fzf for fuzzy search.

## Installing joshuto and opening your first directory

The README lists several installation paths. Building from a checkout needs cargo and rustc at version 1.90 or newer, per the Dependencies section. For a single user, the documented command installs from the local path and overwrites any existing binary:

```bash
~$ cargo install --path=. --force
```

If you would rather install straight from the repository without cloning first, the README gives this variant:

```bash
~$ cargo install --git https://github.com/kamiyaa/joshuto.git --force
```

Package managers cover the common platforms. On macOS or Linux with Homebrew the command is brew install joshuto. Fedora users enable the atim/joshuto COPR and then install the joshuto package. Arch users have joshuto and joshuto-git in the AUR. MacPorts, Gentoo's gentoo-zh overlay and NixOS are all listed as well, and the README includes a Nix flake example plus a nix run github:kamiyaa/joshuto command for a temporary run without installing.

There is also a pre-compiled binary script that needs curl and openssl. The default form installs into $HOME/.local/bin:

```bash
~$ bash <(curl -s https://raw.githubusercontent.com/kamiyaa/joshuto/master/utils/install.sh)
```

The script accepts an INSTALL_PREFIX variable for a custom directory, and a RELEASE_VER variable to pin a specific release. Once installed, running joshuto with no arguments opens the current working directory in the TUI. The README's usage section is a single line for this: joshuto. From there, j and k move the selection, l opens a file or descends into a directory, h goes back to the parent, and ctrl+t opens a new tab. Pressing : enters command mode, and w shows running tasks. To exit into whatever directory you navigated to, the README points to the quit entry in docs/configuration/keymap.toml.md rather than spelling out the binding inline.

## Where joshuto gets in your way

The README is unusually candid about one weak spot. Under TODOs it marks 'Built-in command line' as done, then immediately adds two qualifiers: 'Mostly working' and 'Currently implementation is kind of janky'. Tab autocomplete is listed as in progress. So the : command mode works, but you should not expect the completion behavior of a mature shell. If your workflow depends on typing partial paths and hitting tab, that gap will be noticeable.

Clipboard support is another boundary. Because it relies on xsel, xclip or wl-clipboard being present, a minimal container or a headless SSH session without those binaries will silently lack clipboard integration. The README marks them optional, which is accurate, but optional in this case means the feature is absent rather than degraded.

Image previews depend on terminal graphics support and on the ratatui-image path, and the README defers the details to docs/image_previews rather than describing them inline. If your terminal does not support the relevant protocol, previews will not appear, and the README does not enumerate which terminals qualify.

The larger limitation is scope. joshuto is a terminal application. There is no GUI, no file-manager integration into a desktop environment beyond what you configure in mimetype.toml, and no remote or web interface. If you need to hand a file manager to a colleague who does not use a terminal, this is the wrong tool, and no amount of configuration changes that.

## joshuto against ranger, lf and yazi

The obvious comparison is ranger itself, which joshuto explicitly imitates. ranger is Python, and its configuration lives in a Python-derived rc file, so extending it means writing Python. joshuto is Rust and configures through TOML, which means no scripting language in the config path but also no equivalent escape hatch for arbitrary logic. If you have ranger plugins you rely on, joshuto does not run them.

lf takes a different route again: it is also written in Go and exposes a server-client model where external commands can drive the running instance. That is a meaningfully different extension story from joshuto's static TOML files. yazi is another Rust terminal file manager in the same space, and the related-search data shows people comparing the two directly. The repository material here does not describe yazi's internals, so the honest difference to state is narrower: joshuto's configuration is five TOML files under config/, and its feature list in the README is the concrete inventory of what it does, including tabs, bulk rename, devicons, trash support, a file chooser and exit-to-current-directory.

One point in joshuto's favor is the packaging spread. Fedora COPR, AUR, archlinuxcn, Gentoo, MacPorts, Homebrew and Nix are all documented in the README, which is more distribution coverage than many terminal tools bother to list. That reduces the cost of trying it on a machine you do not control.

## Maintenance, licensing and what an upgrade costs you

The repository is not archived. The last push was on 2026-09-17, six days before this writing, so the project is being touched. The release cadence tells a different story: v0.9.9 landed on 2025-05-20, and before that v0.9.8 and v0.9.7 both landed on 2024-03-15. Between May 2025 and September 2026 there is no tagged release in the list, so if you install from a package manager you may be running code that predates a year of commits on main. Installing with cargo install --git pulls the current main branch instead, which trades stability for recency.

joshuto is licensed LGPL-3.0. The practical consequence for most users is small: running the binary and configuring it through TOML files does not trigger the licence's relinking obligations in the way that statically linking the library into a proprietary product would. If you intend to embed joshuto's code in another program, read the licence text and the repository's LICENSE file rather than relying on a summary. Nothing here is legal advice.

Upgrade cost is mostly configuration drift. Because keymap.toml, mimetype.toml, theme.toml and bookmarks.toml are separate files, a change to one does not force a rewrite of the others, but the project does not document a migration path between versions, and the README does not document rollback. If you customize heavily, keep your config under version control so you can diff it after an upgrade.

## Conclusion

Adopt joshuto if you already use ranger or a vi-style keymap and want a Rust TUI with asynchronous file operations, tabs and image previews, installed with cargo install --git https://github.com/kamiyaa/joshuto.git --force or brew install joshuto. Skip it if you need a file manager that works without a terminal, or if you depend on a stable configuration format, because the README notes the built-in command line is 'kind of janky' and tab autocomplete is still in progress. Before committing, copy the config/ examples into your config directory, verify that mimetype.toml opens your most common file types, and check that xsel, xclip or wl-clipboard is installed if you want clipboard support.

## FAQ

### What is joshuto?

joshuto is a terminal file manager written in Rust and modeled on ranger. The README describes it as a 'ranger-like terminal file manager' and lists tabs, devicons, fuzzy search via fzf, bulk rename, file previews, asynchronous cut/copy/paste, custom themes and trash support among its features.

### How do I install joshuto?

The README documents several routes: cargo install --path=. --force from a checkout, cargo install --git https://github.com/kamiyaa/joshuto.git --force, package managers including Homebrew, Fedora COPR, AUR, MacPorts, Gentoo and Nix, and a pre-compiled binary script run through curl that installs into $HOME/.local/bin by default.

### How do I configure joshuto's keybindings and file associations?

Configuration is split across five TOML files with examples in the repository's config/ directory: joshuto.toml for general settings, keymap.toml for keybindings, mimetype.toml for opening files with applications, theme.toml for colors, and bookmarks.toml for bookmarks. The README points to docs/ for details on each.

## Sources

- [kamiyaa/joshuto on GitHub](https://github.com/kamiyaa/joshuto)
- [License: LGPL-3.0](https://github.com/kamiyaa/joshuto/blob/main/LICENSE)
- [Project website](https://crates.io/crates/joshuto)
- [README](https://github.com/kamiyaa/joshuto/blob/main/README.md)
- [Releases](https://github.com/kamiyaa/joshuto/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kamiyaa-joshuto