elio

Snappy, batteries-included terminal file manager with rich previews, inline images, bulk actions, and trash support.

Documentation

• Installation: https://elio-fm.github.io/install/
• Docs: https://elio-fm.github.io/docs/

---

Features

• Three-pane layout — Places, Files, and Preview side by side
• Rich previews — text, code, documents, archives, media, and more; see Preview Coverage
• Inline images — rendered directly in supported terminals
• Customizable Places and devices — pinned folders plus auto-detected drives and mounts
• Quick actions — Go-to, Open With, and copy-to-clipboard
• Trash management — trash, restore, or permanently delete files
• Keyboard and mouse navigation — browse comfortably either way
• Grid and list views — switch with v, zoom the grid with Ctrl++ / Ctrl+-
• Fuzzy search — find folders and files quickly
• Zoxide jumps — jump to frequent directories from your zoxide history
• Shell integration — install cd-on-exit wrappers for bash, zsh, fish, and Nushell
• Theming — full palette and file-class control via theme.toml

---

Installation

Arch Linux

Install from the AUR with your preferred AUR helper:

paru -S elio

Fedora

Enable the COPR repository and install with dnf:

sudo dnf copr enable miguelregueiro/elio
sudo dnf install elio

Debian and Ubuntu-based Linux

Configure the official apt repository and install with apt:

curl -fsSL https://elio-fm.github.io/elio-apt/install.sh | sudo sh
sudo apt install elio

Manual repository setup is available in elio-apt. To install without adding a repository, download elio_amd64.deb from the latest release.

The apt repository currently publishes amd64 packages.

Homebrew

Install from Homebrew:

brew install elio

Cargo

Install from crates.io:

cargo install elio

elio starts in your current working directory by default. Pass a file or directory path to open it instead.

[!TIP] Recommended: use a Nerd Font in your terminal so icons display correctly.

Running From Source

cargo run --release

---

Example Themes

A few bundled themes are shown below. More are available in examples/themes/. See Theming for theme paths and docs.

Catppuccin Mocha	Navi

|

|

Amber Dusk	Blush Light

|

|

---

Image Previews

Inline visual previews, including images, covers, thumbnails, and rendered pages, work automatically on supported terminals.

Terminal	Protocol	Status
Kitty	Kitty Graphics Protocol	✓ Auto-detected
Ghostty	Kitty Graphics Protocol	✓ Auto-detected
Warp	Kitty direct-placement protocol	✓ Auto-detected
WezTerm	iTerm2 Inline Protocol	✓ Auto-detected
iTerm2	iTerm2 Inline Protocol	✓ Auto-detected
Konsole	Kitty direct-placement protocol	✓ Auto-detected
foot	Sixel	✓ Auto-detected
Windows Terminal	Sixel	✓ Auto-detected
Alacritty	—	Not supported
Other	Kitty Graphics Protocol	Set ELIO_IMAGE_PREVIEWS=1 to enable

Sixel terminals can render large or first-time previews more slowly than Kitty Graphics or iTerm2 Inline backends.

In Konsole, inline previews are temporarily cleared while modal popups are open to avoid rendering artifacts.

Useful environment variables:

Environment Variables

Variable	Effect
ELIO_IMAGE_PREVIEWS=1	Force-enable on unrecognized terminals that support the Kitty Graphics Protocol
ELIO_ZOXIDE_OPTS	Extra options appended to the zoxide interactive picker options
ELIO_DEBUG_PREVIEW	Log image preview activity to elio-preview.log in the system temp directory
ELIO_LOG_MOUSE	Log raw mouse events to elio-mouse.log in the system temp directory

---

Preview Coverage

elio previews many file types directly in the Preview pane:

• Text, source code, Markdown, logs, and structured data such as JSON, YAML, TOML, CSV/TSV, and SQLite
• Documents such as PDFs, ebooks, Office files, OpenDocument files, and Apple Pages
• Images, audio, and video metadata, with inline images, covers, and thumbnails when supported
• Folders, archives, comic archives, torrents, ISO images, and other disk-image-style containers
• Binary files with useful metadata when no richer preview is available

Some richer previews require optional system tools such as Poppler, FFmpeg, resvg, 7-Zip, unar, or FontForge.

See the preview docs: https://elio-fm.github.io/docs/previews/

---

Optional Preview Tools

elio works out of the box, but a few external tools enable richer previews for specific file types:

• poppler for PDF previews
• ffmpeg / ffprobe for media metadata and thumbnails
• resvg for SVG previews
• 7z / unar for archive previews
• fontforge for font previews

See the full optional tools list and package names in the docs: https://elio-fm.github.io/docs/optional-tools/

---

Using elio over SSH

elio works well over SSH for navigation, file operations, text/code previews, and terminal-based workflows.

Rich visual previews depend on the remote host and the local terminal:

• Text and code previews work normally.
• Images, PDF pages, video thumbnails, album art, SVG previews, and archive extras need terminal image support plus optional preview tools installed on the remote host.
• Terminal apps opened through Open With run inside the SSH session.
• System openers such as Enter, o, open, gio, xdg-open, or cmd /c start use the remote host's opener stack. From an SSH session, they may open on the remote host, fail, or do nothing useful.

---

Workflow

elio supports common file-manager actions directly from the keyboard:

• Enter opens folders or selected files with the system default application.
• O opens files through the Open With flow when supported, including terminal apps.
• c copies names, paths, or directory paths using OSC52 or the platform clipboard.
• g opens quick jumps for common locations such as Home, Downloads, config, and Trash.
• d moves files to Trash; D deletes permanently; in the Trash view, d also deletes permanently and r restores.
• f searches folders, while Ctrl+F searches files in the current tree.
• z jumps through zoxide history when zoxide is installed.
• ! opens a shell in the current folder and returns to elio when the shell exits.

Platform details vary for clipboard tools, trash backends, file openers, and shell selection. See the workflow docs: https://elio-fm.github.io/docs/workflow/

---

Change Directory on Quit

elio can leave your shell in the directory you were browsing when you quit:

elio shell install

Restart your shell, then run elio normally. Press q to quit and move your shell to elio's final directory, or Q to quit without changing directories.

See the shell integration docs for uninstall steps, supported shells, and manual setup: https://elio-fm.github.io/docs/shell-integration/

---

Configuration

elio reads configuration from:

Platform	Config file
Linux / BSD	~/.config/elio/config.toml or $XDG_CONFIG_HOME/elio/config.toml
macOS	~/Library/Application Support/elio/config.toml
Windows	%APPDATA%\elio\config.toml

See examples/config.toml for an annotated example, or the configuration docs: https://elio-fm.github.io/docs/configuration/

---

Theming

elio themes are TOML files layered on top of the built-in defaults, so you only need to set the keys you want to change.

Platform	Theme file
Linux / BSD	~/.config/elio/theme.toml or $XDG_CONFIG_HOME/elio/theme.toml
macOS	~/Library/Application Support/elio/theme.toml
Windows	%APPDATA%\elio\theme.toml

See assets/themes/default/theme.toml for the full default theme and examples/themes/ for ready-made themes.

For transparent or terminal-palette setups, see examples/themes/transparent/theme.toml and examples/themes/terminal-ansi/theme.toml.

Theme docs: https://elio-fm.github.io/docs/themes/

---

Controls

Keys marked with * are configurable in [keys] in config.toml; the defaults are shown here. Configurable actions accept one key, a list, or an empty list to unbind the action, such as open_with = ["O", "w"] or delete_permanently = []. Named keys are supported for arrows, enter, space, tab, backtab / shift+tab, backspace, delete / del, pageup, pagedown, home, end, and F1–F12; named keys and modifiers are case-insensitive, so F2, PageUp, and Ctrl+O work. Modifier bindings such as ctrl+o, alt+o, and ctrl+enter are also supported. Setting an action replaces its full default key list.

Navigation

Key	Action
k / ↑ *	Move up
j / ↓ *	Move down
h / ← / Backspace *	Go to parent directory
l / → *	Enter folder
Enter *	Enter folder / open file or selection
g *	Go To menu (g top, d downloads, h home, c config folder, t trash; configurable in [goto])
Home *	Jump to first item
G / End *	Jump to last item
PageUp / PageDown *	Page up / down
Tab / Shift+Tab *	Cycle places
Alt+← / Alt+→ *	Back / forward in history

Search

Key	Action
f *	Fuzzy-find folders in the current tree
Ctrl+F *	Fuzzy-find files in the current tree
z *	Jump with zoxide directory history

File Actions

Key	Action
o *	Open focused item or selection with the system default application
O *	Open With chooser
! *	Open shell in current folder
a *	Create file or folder
d / Del *	Trash; permanently delete if already in trash
D / Shift+Del *	Delete permanently
r / F2 *	Rename / bulk rename
r * (in Trash)	Restore from trash

View

Key	Action
v *	Toggle grid / list view
Ctrl++ / Ctrl+-	Grid zoom in / out
. *	Show / hide dotfiles
s *	Cycle sort (Name → Modified → Size)

Preview

Key	Action
Shift+K / [ *	Step page (PDF, comic, EPUB) or scroll preview up
Shift+J / ] *	Step page (PDF, comic, EPUB) or scroll preview down
Shift+H / Shift+L *	Scroll preview left / right

Selection and Clipboard

Key	Action
Space *	Toggle selection
Ctrl+A *	Select all
y *	Yank (copy)
x *	Cut
p *	Paste
- *	Create absolute symlink from yanked items
_ *	Create relative symlink from yanked items
c *	Copy path details to clipboard

Mouse

Action	Description
Click	Select item
Double-click	Open item
Scroll	Scroll browser or preview
Shift+Scroll	Scroll preview sideways

General

Key	Action
?	Open help overlay
Esc	Cancel / clear selection / close overlay
q *	Quit
Q *	Quit without changing the shell directory

---

License

MIT