How to Install superfile on Debian: A Pretty Fancy and Modern Terminal File Manager

superfile is a modern TUI file manager for the terminal. Written in Go, it lays your files out across several panels at once: a sidebar with your home, pinned directories and disks, one or more file panels, a live preview, and footer panels that show running copy and move operations, metadata and your clipboard. Fuzzy search, bulk selection, archive compression and extraction, a built-in trash bin and a long list of themes are all a keypress away.

superfile is not part of the official Debian archive. The usual install routes are a piped install.sh script or a binary downloaded by hand, and either way keeping it current becomes your job.

The unofficial deb.griffo.io repository removes that friction: it packages superfile as a standard Debian .deb served over APT, so installation and updates use the tooling you already run for the rest of your system.

Install the Latest superfile on Debian: The Short Version

If you only came for the commands, this adds the repository and installs the latest superfile .deb package on Debian:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null
sudo apt update
sudo apt install superfile

Then start it with spf. The rest of this guide explains what each command does, why the command is not called superfile, how to keep it up to date, and what to check when something goes wrong.

What Makes superfile Special?

🗂️ Multi-panel layout - Open several file panels side by side, plus a sidebar, a preview pane and footer panels for processes, metadata and the clipboard.
👀 Rich previews - Syntax-highlighted code, directory listings and inline images in terminals that speak the Kitty graphics protocol.
🔍 Fast search - Filter the current directory as you type with /.
✅ Selection mode - Select many files at once and copy, cut or delete them in one go.
📦 Archives built in - Compress to .zip and extract archives without leaving the file manager.
🗑️ Trash bin - Deletes go to the trash by default, so a slip of the finger is recoverable.
📌 Pinned directories - Pin the folders you visit most to the sidebar.
🎨 Themes and hotkeys - Over twenty bundled themes, fully remappable hotkeys and a ready-made Vim-style keymap.
🔌 Plugins - Optional exiftool metadata, MD5 checksums and zoxide-powered directory jumping.
📦 Single static binary - A self-contained Go build with no runtime dependencies.

Why Use the deb.griffo.io Repository?

Easy installation and updates through APT, no curl-to-shell installer.
Automatic dependency management handled by Debian packaging, including sensible recommendations for optional helpers.
Always tracks upstream releases so you stay close to the latest superfile.
No compiling from source and no Go toolchain to maintain.
Works across supported Debian releases, with the codename detected automatically.

Prerequisites

Before you start, make sure you have:

A Debian-based system (Bookworm 12, Trixie 13, Forky, or Sid)
sudo privileges
curl installed (sudo apt install curl if needed)

Packages are available for both amd64 and arm64. superfile draws its file and folder icons with a Nerd Font, so for the full look set one as your terminal font. It works without one too; see the troubleshooting section.

Step 1: Add the deb.griffo.io Repository

Add the signing key and repository source:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

What each command does:

Create the keyrings directory - ensures /etc/apt/keyrings exists with proper permissions.
Install the GPG key - downloads the repository key and de-armours it into a dedicated keyring for verification.
Add the repository - writes a signed-by source line, with lsb_release -sc supplying your Debian codename.
Update the package list - refreshes APT so it knows about the new packages.

Step 2: Update the Package List

If you skipped the last line, run the update now:

sudo apt update

Step 3: Install superfile

Install superfile with APT:

sudo apt install superfile

APT also pulls in xdg-utils, which the package recommends so that pressing enter on a file opens it in your desktop’s default application.

Optional Helpers

superfile itself has no hard dependencies, but a handful of suggested packages unlock extra features:

sudo apt install zoxide libimage-exiftool-perl ffmpeg poppler-utils xclip

zoxide - powers the directory-jumping modal (see How to install zoxide on Debian for the latest version).
libimage-exiftool-perl - provides exiftool for the detailed metadata plugin.
ffmpeg and poppler-utils - enable video and PDF previews.
xclip or wl-clipboard - clipboard integration on X11 or Wayland respectively; pick the one that matches your session.

Step 4: Verify the Installation

Here is the one thing that trips everyone up: the package is called superfile, but the command it installs is spf. That is upstream’s own naming, not a packaging quirk. Confirm the version:

spf --version

You should see output similar to:

superfile version v1.6.0

spf --help lists every flag and subcommand. There is no man page upstream, so --help is the reference.

Getting Started with superfile

Launching and Quitting

# Open superfile in the current directory
spf

# Open a specific directory
spf ~/Projects

# Open several directories, one file panel each
spf ~/Downloads ~/Documents

Press q or esc to quit, and ? at any time to bring up the full hotkey list.

Moving Around

The default hotkeys work with both arrow keys and Vim-style letters:

up/down or k/j move the cursor.
enter, right or l open a folder or file; h, left or backspace go to the parent directory.
/ searches the current directory, . toggles dotfiles, and o opens the sort menu (R reverses the order).
P pins or unpins the current directory in the sidebar.

Panels

n opens a new file panel and w closes the focused one; tab or L moves to the next panel, shift+left or H to the previous one.
s, p and m move focus to the sidebar, processes panel and metadata panel. Press the same key again to return to the file panel.
f shows or hides the preview pane, and F toggles the whole footer.

Folder sizes are only calculated when the metadata panel has focus, which keeps browsing fast on large trees.

File Operations

superfile’s default keymap follows a simple rule: every action that changes files uses ctrl, so plain letters never touch your data.

Action	Hotkey
Create a file (end the name with `/` for a folder)	`ctrl+n`
Rename	`ctrl+r`
Copy / cut / paste	`ctrl+c` / `ctrl+x` / `ctrl+v`
Move to trash	`ctrl+d`
Delete permanently	`D`
Compress to `.zip` / extract	`ctrl+a` / `ctrl+e`
Open file / current directory in your editor	`e` / `E`
Copy the file path / working directory	`ctrl+p` / `c`

Copied and cut items appear in the clipboard panel, and long operations report progress in the processes panel. Deleting on an external drive skips the trash and removes files directly.

Selection Mode

Press v to switch the focused panel into selection mode. Toggle individual items with enter, extend the selection while moving with shift+up/shift+down (or K/J), or grab everything in the directory with A. Copy, cut and delete then act on the whole selection.

Running Commands

: opens a shell prompt that runs a command in the current directory and reports its exit code.
> opens the SPF prompt, which understands cd <path>, open <path> (new panel) and split.

Configuration, Themes and Hotkeys

superfile creates its configuration on first launch. To see exactly where everything lives:

spf path-list

On Linux the important files are:

~/.config/superfile/config.toml - settings
~/.config/superfile/hotkeys.toml - key bindings
~/.config/superfile/theme/ - custom themes
~/.local/state/superfile/superfile.log - the log file

Switching theme is a one-line change in config.toml:

theme = "gruvbox"

Bundled themes include catppuccin-mocha (the default), dracula, gruvbox, nord, rose-pine, tokyonight and many more. If you live in Vim, copy upstream’s Vim-style hotkeys into hotkeys.toml.

After upgrading to a release that adds new settings, fill in any missing entries without touching the values you have changed:

spf --fix-config-file
spf --fix-hotkeys

Enabling the Plugins

Once the helper packages are installed, turn their plugins on in config.toml:

metadata = true
zoxide_support = true

Restart superfile, then press z for the zoxide jump modal. Set code_previewer = "bat" if you prefer bat for syntax highlighting in previews.

Change Directory on Quit

By default your shell stays where it was when superfile exits. To land in the directory you were browsing instead, set this in config.toml:

cd_on_quit = true

Then add upstream’s wrapper function to ~/.bashrc (the same function works in ~/.zshrc):

spf() {
    os=$(uname -s)

    # Linux
    if [[ "$os" == "Linux" ]]; then
        export SPF_LAST_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/superfile/lastdir"
    fi

    # macOS
    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
    }
}

Reload with source ~/.bashrc. The same wrapper also powers the Q hotkey, which quits and changes to the current folder on demand. Fish users will find the equivalent function in upstream’s cd_on_quit folder.

Keeping superfile Updated

Because superfile arrived via APT, updates come with the rest of the system:

sudo apt update && sudo apt upgrade

Whenever deb.griffo.io ships a newer superfile, apt upgrade installs it automatically. superfile also checks GitHub for new releases once a day when you exit; since APT now owns the binary, you can silence that notice in config.toml:

auto_check_update = false

Other Tools from deb.griffo.io

The repository packages plenty of tools that fit naturally alongside superfile:

zoxide - a smarter cd that powers superfile’s jump modal.
Yazi - another blazing fast terminal file manager, worth comparing.
eza - a modern replacement for ls.
Ghostty - a fast terminal emulator that renders superfile’s image previews.
restic - fast, encrypted, deduplicated backups for the files you manage.

Troubleshooting

GPG or Key Errors

If APT reports an unsigned repository or an invalid key, import it again:

curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Package Not Found

If APT cannot see the superfile package:

Re-run sudo apt update after adding the repository.
Confirm your release is supported (Bookworm, Trixie, Forky, or Sid).
Inspect the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list.

”superfile: command not found”

The package is installed; the command is simply named differently. Run spf, or confirm with dpkg -L superfile | grep bin.

Icons Show as Boxes or Question Marks

Your terminal is not using a Nerd Font. Install one and select it in your terminal’s settings, or turn icons off in config.toml:

nerdfont = false

Borders and Layout Look Broken

Make sure your locale is UTF-8 (locale should show a .UTF-8 value). If box characters are still misaligned, try:

RUNEWIDTH_EASTASIAN=0 spf

Image Previews Do Not Appear

Inline images need a terminal that supports the Kitty graphics protocol, such as kitty, WezTerm or Ghostty. Elsewhere superfile falls back to text previews.

Conflicting superfile Installations

If you previously used upstream’s install script, an older spf in /usr/local/bin will take precedence over the packaged one:

which -a spf

Remove the stray binary (sudo rm /usr/local/bin/spf) so the APT-managed /usr/bin/spf is the one you run.

Uninstalling

Remove superfile with:

sudo apt remove superfile

Your configuration in ~/.config/superfile and data in ~/.local/share/superfile are left alone; delete those directories too if you want a clean slate. To also drop the repository and key:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Conclusion

Installing superfile from deb.griffo.io gives Debian users a polished, multi-panel file manager in the terminal without an install script or manual updates. Previews, selection mode, archives, a trash bin and a theme for every taste come in one small binary, and keeping it current is just another apt upgrade.

Remember to type spf, pick a Nerd Font, and enable cd_on_quit if you want superfile to double as your way of navigating the shell.

Frequently Asked Questions

How do I install the latest superfile on Debian?

Add the deb.griffo.io APT repository and its signing key, then run sudo apt install superfile. The repository tracks upstream superfile releases, so you get the latest packaged version rather than a build frozen when your distribution was released.

Is there a `.deb` package for superfile?

Yes. deb.griffo.io publishes superfile as a signed .deb for Debian. You could download that .deb and install it by hand, but adding the repository is the better option: APT then resolves dependencies and picks up new versions on its own.

Why is the command `spf` and not `superfile`?

That is upstream’s choice: superfile has always shipped its binary as spf. The Debian package keeps the project name, superfile, and installs /usr/bin/spf.

How do I update superfile to the latest version?

Run sudo apt update && sudo apt upgrade. You can also set auto_check_update = false in config.toml, since APT now takes care of new releases.

How do I install superfile on Ubuntu?

Exactly the same way; lsb_release -sc simply resolves to a different codename. There is a companion guide with the Ubuntu specifics: How to install superfile on Ubuntu.

Which Debian releases are supported?

Bookworm 12, Trixie 13, Forky and Sid, on both amd64 and arm64. Because the repository line is built from lsb_release -sc, the matching suite is selected for you.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream superfile project.