DEV Community

Cover image for Open Source Project #129: superfile — The Modern Terminal File Manager That Doesn't Sacrifice Looks for Speed
WonderLab
WonderLab

Posted on

Open Source Project #129: superfile — The Modern Terminal File Manager That Doesn't Sacrifice Looks for Speed

#opensource #tooling #tui #productivity

Introduction

"Pretty fancy and modern terminal file manager"

This is article #129 in the "One Open Source Project a Day" series. Today's project is superfile — a modern terminal file manager written in Go on top of the Bubbletea framework, known for its polished looks and Vim-friendly hotkey design.

Terminal file managers have a long lineage: mc (Midnight Commander) from 1994 is still maintained, ranger built a devoted following with its Python-powered three-column view, and lf took the minimal approach. superfile, appearing in 2024, asks a different question: if you redesigned a terminal file manager from scratch against today's TUI standards, what would it look like?

19,170 Stars. Created March 2024. Actively maintained.

What You'll Learn

  • superfile's five-panel layout and what each panel does
  • Vim-friendly hotkey design (normal mode vs. selection mode)
  • Practical features: image preview, zoxide integration, cd-on-quit
  • Themes and plugin extensions
  • Comparison with ranger, lf, yazi, and other peers

Prerequisites

  • Basic terminal / command-line experience
  • Familiarity with Vim basics (j/k navigation, visual mode) helps understand the hotkeys, but isn't required

Project Background

Overview

superfile (command alias spf) is a TUI (Text User Interface) file manager written in Go, built on Charm's Bubbletea framework. Its design goal is not minimalism — it's a visually modern, efficient file management experience directly in the terminal.

Author / Team

  • Author: yorukot (+ core maintainer lazysegtree)
  • Language: Go
  • License: MIT
  • Website: superfile.dev
  • Command: spf

Project Stats

  • ⭐ GitHub Stars: 19,170+
  • 🍴 Forks: 587+
  • 📄 License: MIT
  • 📅 Created: 2024-03-19

Installation

macOS / Linux (one-liner) 

bash -c "$(curl -sLo- https://superfile.dev/install.sh)"
Enter fullscreen mode Exit fullscreen mode

Windows 

# PowerShell
powershell -ExecutionPolicy Bypass -Command "Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://superfile.dev/install.ps1'))"

# Winget
winget install --id yorukot.superfile

# Scoop
scoop install superfile
Enter fullscreen mode Exit fullscreen mode

macOS (Homebrew) 

brew install superfile
Enter fullscreen mode Exit fullscreen mode

Once installed, just run:

spf
Enter fullscreen mode Exit fullscreen mode

Press q or Esc to exit.

Features

Five-Panel Layout

superfile launches with five panels — one of its most visually distinctive traits compared to other terminal file managers:

Panel Hotkey Purpose
File panel Default focus Main area for browsing and file operations; multiple panels can coexist
Sidebar s Pinned directory bookmarks + mounted disks/devices
Processes p Progress of background file operations (copy/move)
Metadata m File details; folder size only shown when this panel is focused
Clipboard — Queue of copied/cut items

There's also a command execution bar opened with :.

Press f to toggle the file preview window; press F (Shift+f) to toggle all footer panels.

Multiple File Panels

One of superfile's most-cited features: you can open multiple side-by-side file panels in a single screen.

  • n — create a new file panel
  • w — close the focused file panel
  • Tab / L (Shift+l) — move to the next panel
  • Shift+Left / H (Shift+h) — move to the previous panel

This is particularly useful for cross-directory copy/move operations, or for comparing the contents of two directories side by side.

Vim-Style Navigation

superfile's hotkeys are designed with Vim users in mind:

File panel navigation:

Action Hotkey
Move up ↑ or k
Move down ↓ or j
Open directory / file Enter or l
Go to parent directory h or Backspace
Search current directory /
Show/hide dotfiles .
Sort options (name/size/date) o
Reverse sort order R (Shift+r)

Selection Mode (Vim Visual Mode Analogue)

superfile has two modes, displayed in the lower-right corner of the file panel:

  • Browser mode (default): single-item operations
  • Select mode: bulk operations

Press v to toggle between them.

In selection mode:

Action Hotkey
Select / deselect current item Enter or L (Shift+l)
Select while moving up Shift+↑ or K (Shift+k)
Select while moving down Shift+↓ or J (Shift+j)
Select all in current directory A (Shift+a)

Note: copy, cut, and delete work in selection mode. Creating files/directories and renaming only work in Browser mode.

File Operations

Action Hotkey
New file Ctrl+n
New directory Ctrl+n, then append / to the name
Create nested path + file in one dir/subdir/filename
Rename Ctrl+r
Copy Ctrl+c
Cut Ctrl+x
Paste Ctrl+v
Move to trash Ctrl+d
Permanently delete Ctrl+Delete or Delete

Pin a directory to the sidebar: navigate into the target directory and press P (Shift+p) to pin/unpin.

Image Preview

superfile can render images inline in the file preview pane. Enable it by setting show_image_preview: true in the config (off by default).

Rendering quality depends on the terminal:

  • Terminals supporting the Kitty graphics protocol (Kitty, WezTerm, etc.) get high-quality image rendering
  • Other terminals fall back to Unicode half-block character approximations

cd on quit

A small but extremely useful feature: when you exit superfile, your terminal's working directory automatically changes to wherever you were last browsing.

Enable cd_on_quit: true in config.toml, then add a shell wrapper function to your .bashrc:

# ~/.bashrc
spf() {
    os=$(uname -s)
    if [[ "$os" == "Linux" ]]; then
        export SPF_LAST_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/superfile/lastdir"
    fi
    if [[ "$os" == "Darwin" ]]; then
        export SPF_LAST_DIR="$HOME/Library/Application Support/superfile/lastdir"
    fi
    command spf "$@"
    [[ ! -f "$SPF_LAST_DIR" ]] || { . "$SPF_LAST_DIR"; rm -f -- "$SPF_LAST_DIR" > /dev/null }
}
Enter fullscreen mode Exit fullscreen mode

After that, spf becomes a "browse and land" workflow: open superfile → navigate to the target directory → exit → you're already there, ready to work.

Deep Dive

Plugin System

superfile plugins are enabled via the config file. Three official plugins are available:

Zoxide integration (zoxide_support: true)

Requires zoxide to be installed first. Once enabled, press z to open the zoxide jump modal — type to search your frecency-ranked directories, use arrow keys to navigate results, press Enter to jump. For engineers switching between dozens of project directories daily, this is one of the highest-frequency features.

exiftool metadata (metadata: true)

Requires exiftool. Displays rich EXIF metadata in the metadata panel — particularly useful for image, video, and audio files.

MD5 checksum (enable_md5_checksum: true)

No additional dependencies. Shows the MD5 checksum of the selected file in the metadata panel. Note: computing checksums requires reading the full file, so it can be slow for large files.

Theme System

superfile has a dedicated theme configuration layer for customizing all UI colors: foreground, background, border, highlight, and more.

Browse themes: superfile.dev/list/theme-list

To create a custom theme: add a new .toml file in the themes directory following the official theme format.

Configuration

Find your config file paths:

spf pl   # "pl" = path locations — lists all superfile-related file paths
Enter fullscreen mode Exit fullscreen mode

Key config options (config.toml):

Setting Description
theme Theme name
editor Editor invoked when pressing Enter on a file
dir_editor Editor invoked when opening a directory
cd_on_quit Change terminal path to last-browsed directory on exit
auto_check_update Check for updates on exit (at most once per day)
default_open_file_preview Show file preview pane on startup
show_image_preview Render images in the preview pane
file_size_use_si Display file sizes with SI units (kB/MB, base 1000)

Comparison: superfile vs Other Terminal File Managers

Tool Language Startup Multi-panel Image preview Learning curve
superfile Go Fast ✅ (N panels) ✅ Low–medium
ranger Python Slow Fixed 3 columns ✅ (needs config) Medium
lf Go Very fast — ✅ (needs ext tools) Low
yazi Rust Very fast — ✅ (built-in) Low–medium
nnn C Very fast — Limited Medium–high
mc C Fast Fixed 2 panels — Low

superfile vs ranger: ranger is more mature with a larger plugin ecosystem, but Python startup overhead is noticeable; ranger's three-column layout is fixed, while superfile's multi-panel design is flexible.

superfile vs lf: lf pursues minimalism — it's maximally configurable via shell scripts, ideal for power users who want to build everything themselves. superfile offers a more complete out-of-the-box experience without requiring configuration to look and work well.

superfile vs yazi: Both emerged around 2024 as "modern TUI file managers." yazi is Rust-based and emphasizes async architecture and raw performance. superfile's multi-panel design and more polished default UI are the differentiating points.

Who It's For

✅ superfile shines when:

  • You want a nice-looking terminal file manager without deep configuration
  • You need to work with multiple directories simultaneously (multi-panel)
  • You're a Vim user looking for fast ramp-up time
  • You want image preview or zoxide integration out of the box

⚠️ May not be the best fit when:

  • Raw startup speed is the top priority (lf/yazi/nnn are faster)
  • You need heavy custom command and script integration (lf is more flexible)
  • Windows is your primary platform (Windows support is still incomplete)

Resources

Official Links

Summary

superfile addresses a real frustration: "I use the terminal for file management every day, but the available tools are either ancient-looking, difficult to configure, or both." Its answer: make looks a first-class priority, ship a complete feature set out of the box, and keep the extension surface open.

Three design choices worth highlighting:

Multiple file panels: Most peers offer a fixed one- or two-column view. superfile lets you freely create and close file panels, which is a genuine workflow improvement when you're moving files between three different directories at once — something that would require three separate cd commands and a lot of mental tracking in a single-panel tool.

cd on quit: Looks like a minor feature, but it changes how you use the tool. spf stops being "look at files" and becomes "browse to find where I need to be, then continue working there." Combined with the zoxide plugin, the friction of directory navigation drops substantially.

Visible process and clipboard panels: Background file operations (copy, move) and the clipboard queue exist in most file managers, but they're invisible. Putting them on-screen removes the "did my copy finish?" uncertainty that causes people to either wait or lose track entirely.

19k Stars and steady community contribution signal it found its audience. If you're looking for a modern, good-looking, low-friction terminal file manager, bash -c "$(curl -sLo- https://superfile.dev/install.sh)" is the fastest way to find out whether it fits your workflow.

Explore PrimeSkills — a curated marketplace of AI agents and skills, each validated against real enterprise workflows. No hype, just what actually works.

Visit my personal site for more insights and interesting products.

Top comments (0)