https://github.com/alexm-dev/runa
A fast and lightweight terminal file manager written in Rust
https://github.com/alexm-dev/runa
cargo cli cross-platform file-explorer file-manager filebrowser filemanager filesystem productivity rust terminal tui
Last synced: 2 months ago
JSON representation
A fast and lightweight terminal file manager written in Rust
- Host: GitHub
- URL: https://github.com/alexm-dev/runa
- Owner: alexm-dev
- License: apache-2.0
- Created: 2025-11-28T18:09:21.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-04-19T15:49:21.000Z (2 months ago)
- Last Synced: 2026-04-19T17:27:46.502Z (2 months ago)
- Topics: cargo, cli, cross-platform, file-explorer, file-manager, filebrowser, filemanager, filesystem, productivity, rust, terminal, tui
- Language: Rust
- Homepage: https://crates.io/crates/runa-tui
- Size: 1.44 MB
- Stars: 15
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE-APACHE
- Security: SECURITY.md
Awesome Lists containing this project
README
# `runa - rn`
[](https://github.com/alexm-dev/runa/actions/workflows/rust.yml)
[](https://github.com/alexm-dev/runa/releases)
[](https://crates.io/crates/runa-tui)
[](https://aur.archlinux.org/packages/runa)
[](https://github.com/alexm-dev/runa)
[](#license)
> **A fast, lightweight, and extremely customizable terminal file manager carved in Rust.**
Full Configuration Guide •
Installation Guide •
Quick Start •
General Settings •
Theme Configuration •
Key Bindings
- **Rich File Actions:** Move, filter, copy, rename, tabs, and more, all with the keyboard.
- **Extremely Customizable:** Tweak keybindings, colors, and layout via TOML.
- **Blazing Fast:** Instant navigation, even in huge directory trees.
- **Minimal Dependencies:** Only the essential crates; advanced features are opt-in.
- **Cross-Platform:** Works on Linux, macOS, and Windows.
- **Keyboard-Driven:** Every action accessible by keybindings. No mouse needed.
- **Integrated Find (`fd` required):** Blazingly fast file search.
**runa - rn** is a feature-rich terminal file manager with a concurrent, multi-threaded architecture designed for speed and a minimal footprint.
It allows you to navigate directories, view file listings, and perform typical file manager actions.
What makes runa fast?
- **Multi-threaded engine:** Spawns 9 lightweight dedicated worker threads (with `crossbeam_channel`) for I/O, preview, find, and file operations, so UI is never blocked.
- **Essential-only Rust crates:** No external TUI frameworks or bloat.
- **Direct terminal rendering:** Uses [ratatui](https://ratatui.rs/) & [crossterm](https://github.com/crossterm-rs/crossterm).
- **Optional blazing-fast find:** Integrates with [fd](https://github.com/sharkdp/fd) for recursive fuzzy search.
- **Blazingly lightweight:** The `rn` binary is compact (typically 1.6-2 MB, depending on operating system and architecture).
- **Minimal memory footprint**: Optimized for low RAM usage.
**runa** is very customizable, checkout the [Configuration](docs/configuration.md) docs for all the available options.
> [!IMPORTANT]
> **runa** is a work in progress. It is being actively developed and features may change over time.
## Changelog
For a detailed list of changes and release notes, see [CHANGELOG.md](./CHANGELOG.md).
## Installation
### Cargo:
```bash
cargo install runa-tui
```
### Arch Linux (AUR)
You can install runa from the [AUR](https://aur.archlinux.org/packages/runa) using an AUR helper like `paru` or `yay`:
```bash
yay -S runa
# or for binaries through the AUR
yay -S runa-bin
```
### Homebrew
You can install runa via homebrew.
```bash
brew tap alexm-dev/tap
brew install runa
```
### Scoop (Windows)
You can install runa via scoop.
```bash
scoop add bucket https://github.com/alexm-dev/scoop-bucket
scoop install runa
```
### Pre-compiled Binaries
If you'd like to download Pre-compiled binaries instead of installing runa as a crate in cargo or via the AUR,
you can grab the latest binaries for Linux, Windows and macOS from the [Release](https://github.com/alexm-dev/runa/releases) page.
After downloading, add the `rn` (Linux/macOS) or `rn.exe` (Windows) binary to your system `PATH` to use runa from your terminal.
> [!TIP]
> **Checksum & Attestation Check:**
> All releases starting with v0.5.11 are **immutable**.
> Each release includes a `Release Attestation` json file that verifies that the release is immutable.
>
> You can verify the integrity of the release archives using the attestation verification with the GitHub CLI:
>
> ```bash
> gh attestation verify --repo alexm-dev/runa
> ```
>
> You can also verify the integrity of the release archives using the `SHA256SUMS.txt` file in the [Release](https://github.com/alexm-dev/runa/releases) page.
>
> Unix
> ```bash
> sha256sum -c SHA256SUMS.txt
> ```
> This checks all the checksums of the SHA256SUMS.txt.
> To check a specific release archive:
> ```bash
> grep runa-linux-x86_64.tar.gz SHA256SUMS.txt | sha256sum -c
> ```
>
> Windows
> ```powershell
> Get-FileHash runa-windows-x86_64.zip -Algorithm SHA256
> ```
> Compare the output with the corresponding entry in `SHA256SUMS.txt`.
### Build from source
Clone the repo and build with Cargo:
```bash
git clone https://github.com/alexm-dev/runa.git
cd runa
cargo build --release
```
### Usage
After installation, start runa with: `rn`
> [!TIP]
> **Icons** (for files, folders, etc.) are disabled by default, but can be enabled in your `runa.toml`.
> To display them correctly, use a **Nerd Font** or a patched font in your terminal.
> Without a Nerd Font, icons may appear incorrectly and the UI may not render as intended.
## Optional Enhancements
`runa` is designed to be lightweight and standalone. However, some advanced features leverage specialized external tools:
* **Fuzzy Search:** To enable fast, recursive fuzzy finding, install **[fd](https://github.com/sharkdp/fd)**.
* If `fd` is detected in your `PATH`, the search feature will be enabled automatically.
* Without it, `runa` remains a fully functional file manager but will notify you if you attempt a recursive search.
* Also enables `move_file` auto-complete if `fd` is enabled.
* **Preview Syntax coloring**: To enable syntax coloring in the preview pane, install **[bat](https://github.com/sharkdp/bat)**
* If `bat` is detected and installed, you can switch method in the runa.toml to `method = "bat"`.
* Without it, `runa` uses the `internal` preview method, which is a plain preview method useful for extra speed without syntax highlighting.
## Configuration
By default, runa checks for configuration in these locations, in order:
1. If the environment variable `RUNA_CONFIG` is set, its value is used as the config path.
2. If `XDG_CONFIG_HOME` is set, runa looks for:
```sh
$XDG_CONFIG_HOME/runa/runa.toml
```
3. Otherwise, the fallback is:
```sh
$HOME/.config/runa/runa.toml
```
(On Windows, this means inside the user's config folder.)
#### Overriding the config path
You can explicitly set a custom config location by setting the environment variable `RUNA_CONFIG`.
**Example:**
```sh
export RUNA_CONFIG=/path/to/your/runa.toml
```
You can generate a default config using the --init or --init-full flag:
```bash
rn --init
# For the whole configuration options runa.toml
rn --init-full
# For help with all the configuration options.
rn --config-help
```
This will generate a config in the default config path.
## Roadmap
runa is in active development, with future releases focusing on expanding functionality while keeping it fast and lightweight.
### Planned Features
- [ ] Image Previews: Support for Sixel/Kitty graphics protocols
### Completed Features
- [x] Tabs: Spawn and manage multiple tabs of runa
- [x] Syntax Highlighting: `bat` integration for the preview pane
- [x] Search & Discovery: Integrated fuzzy finding (`fd` support)
- [x] File Operations: Copy, move, delete, and rename from within the UI
- [x] Content Search: Text search and filtering
- [x] Performance: Reactive rendering
- [x] UI Customization: Pane-specific styling and Hex color support
- [x] Navigation Context: Persistent Parent (Origin) and Preview panes
> See [CHANGELOG.md](./CHANGELOG.md) for version details and release history.
---
---
## Support & Contribute
If you enjoy using **runa**, you can help the project grow:
* ⭐ **Star the Repo:** It helps more people discover runa :)
* 🐛 **Report Bugs:** Open an issue if something doesn't work as expected.
* 💡 **Feature Requests:** Suggest new ideas in the [Discussions](https://github.com/alexm-dev/runa/discussions) tab.
* 🦀 **Contribute:** Pull requests are always welcome! Checkout the [CONTRIBUTING guide](CONTRIBUTING.md) for more info.
## Special Thanks
Many thanks to [@lmartinez-mirror](https://github.com/lmartinez-mirror), the maintainer of [runa-bin](https://aur.archlinux.org/packages/runa-bin), for maintaining the binary AUR package.
Many thanks to [@sharkdp](https://github.com/sharkdp) for `fd` and `bat`, excellent CLI tools runa integrates with for fuzzy finding and syntax preview.
## Credits & Ecosystem
`runa` stands on the shoulders of these incredible Rust crates:
- **Terminal UI:**
- [Ratatui](https://ratatui.rs): Direct, fast terminal rendering.
- [Crossterm](https://github.com/crossterm-rs/crossterm): Cross-platform terminal I/O.
- **Configuration:**
- [Serde](https://serde.rs): Data serialization/deserialization.
- [toml-rs](https://github.com/toml-rs/toml): TOML parsing.
- **Concurrency:**
- [Crossbeam-channel](https://github.com/crossbeam-rs/crossbeam): Multi-threaded communication (worker threads).
- **Optional Integrations:**
- [fd](https://github.com/sharkdp/fd): High-performance fuzzy finder (search enhancement).
- [bat](https://github.com/sharkdp/bat): Syntax-highlighted file previews.
## License
This project is dual licensed under the MIT OR Apache-2.0 license.
See the [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE) files for details.