How to Install and Use Superfile on Windows, macOS, and Linux

67

Software & Tools

Superfile is a terminal user interface (TUI) file manager. Instead of repeatedly using commands such as cd, ls, cp, and mv, you can browse and manage files through an interactive interface inside your terminal. Its executable is spf.

This guide covers installing Superfile on Windows, macOS, and Linux, then using it to navigate directories, copy and move files, manage multiple panels, and configure the basics. If you want a deeper explanation of TUIs, platform differences, architecture, and alternatives, see the Complete Superfile Guide.

Before You Install Superfile

Superfile runs inside a terminal. On Windows, you can use a terminal such as Windows Terminal or PowerShell. On macOS, you can use Terminal.app, iTerm2, or another compatible terminal. On Linux, use your preferred terminal emulator and shell.

Superfile uses Nerd Font glyphs for its interface and icons, and the official documentation recommends using a Nerd Font with your terminal. Superfile can still run without one, but parts of the interface may not display as intended. If you prefer not to install a Nerd Font, you can disable Nerd Font support in the configuration.

Superfile supports Windows natively, with official installation methods for PowerShell, Winget, and Scoop. If your workflow already uses Windows Subsystem for Linux (WSL), you can instead install Superfile inside the WSL distribution using the Linux installation method.

How to Install Superfile on Windows

Windows offers three installation methods. Choose one.

Option 1: Winget

Open Windows Terminal or PowerShell and run:

winget install --id yorukot.superfile

Restart your terminal after installation so the new binary is available in your PATH.

Option 2: Scoop

If you use Scoop, run:

scoop install superfile

Option 3: PowerShell Install Script

Run this one-line command in PowerShell:

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

After any of these methods, verify the installation:

spf --version

If you see a version number, Superfile is installed. If you see spf: The term 'spf' is not recognized, restart your terminal or check that the installation directory is in your PATH.

Superfile supports Windows natively. Terminal-dependent features can still vary with the terminal emulator you use. In particular, image preview support depends on terminal capabilities rather than PowerShell itself. If you prefer a Linux environment on Windows, you can also install Superfile inside WSL.

How to Install Superfile on macOS

macOS offers two methods.

Option 1: Homebrew

If you have Homebrew installed, run:

brew install superfile

Homebrew downloads the correct binary for your architecture, whether Intel or Apple Silicon.

Option 2: Install Script

Run the official install script with curl:

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

Or with wget:

bash -c "$(wget -qO- https://superfile.dev/install.sh)"

Verify the installation:

spf --version

How to Install Superfile on Linux

Linux installation varies by distribution. Superfile provides a generic installation script, while several package-manager options listed in the official documentation are community maintained.

Arch Linux

sudo pacman -S superfile

NixOS

nix profile install github:yorukot/superfile#superfile

All Other Distributions

Use the generic install script. With curl:

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

Or with wget:

bash -c "$(wget -qO- https://superfile.dev/install.sh)"

If you want to inspect the script before running it, download it first:

curl -sLo install-superfile.sh https://superfile.dev/install.sh
less install-superfile.sh
bash install-superfile.sh

Verify the installation:

spf --version

How to Launch Superfile

Open a terminal and run:

spf

Superfile opens in your current working directory. If you want to start in a specific folder, navigate there first:

cd ~/Downloads
spf

You can also launch Superfile with a specific file selected:

spf ~/Documents/report.pdf

This opens the parent directory with report.pdf highlighted. To exit Superfile, press q or Esc.

Learn the Essential Superfile Controls

Superfile is keyboard-driven. You do not need a mouse. The essential controls are simple enough to learn in a few minutes.

Navigate

• Press Down or j to move the cursor down.
• Press Up or k to move the cursor up.
• Press Enter, Right, or l to open the selected file or enter the selected directory.
• Press h, Left, or Backspace to return to the parent directory.

Search and Filter

• Press / to open the search bar. Type a filename to filter the current directory.
• Press . to toggle hidden files on or off.

Preview

• Press f to show or hide the file preview panel.
• Press m to focus the metadata panel, which shows file size, permissions, and modification date.

Quit

• Press q or Esc to exit Superfile and return to your shell.
• Press Q (Shift+Q) to use Superfile’s cd_quit action. Changing the parent shell to the directory you were browsing requires the cd_on_quit shell integration to be configured first.

How to Create, Copy, Move, Rename, and Delete Files

These are the file operations you will use most often. Each maps to a keyboard shortcut.

Create a File or Folder

Press Ctrl+N. Superfile prompts you to enter a name. End the name with a forward slash to create a folder. For example, type notes.txt to create a file, or Archive/ to create a folder.

Copy a File

Select the file and press Ctrl+C. The file is marked for copy. Navigate to the destination directory and press Ctrl+V to paste. For directories, the copy is recursive.

Move a File

Select the file and press Ctrl+X to cut it. Navigate to the destination and press Ctrl+V to move it there. This is equivalent to the shell command mv.

Rename a File

Select the file and press Ctrl+R. An inline text field appears. Type the new name and press Enter to confirm.

Delete a File

Select the file and press Ctrl+D or the Delete key. Superfile normally sends deleted items to the trash rather than deleting them directly. The official documentation notes that files on an external hard drive may instead be deleted directly, so check the selected items carefully before confirming deletion.

Press Shift+D to use Superfile’s permanent-delete action, which bypasses the normal trash workflow. Treat this as a destructive operation and verify the selected items before continuing, especially when browsing system directories or running Superfile with elevated privileges.

Select Multiple Files

Press v to switch between normal mode and selection mode. In selection mode, use Shift+Down or J (Shift+J) to select downward from the cursor, and Shift+Up or K (Shift+K) to select upward. Press A (Shift+A) to select all items in the current file panel. Once the required items are selected, operations such as Ctrl+C, Ctrl+X, and Ctrl+D apply to the selected items.

How to Use Multiple Panels

Multiple panels let you copy or move files between directories without typing paths. Here is a practical example.

Suppose you have report.pdf in ~/Downloads and you want it in ~/Documents/Work.

1. Launch Superfile in ~/Downloads.
2. Press n to create a new file panel.
3. Press Tab to switch focus to the new panel.
4. Navigate to ~/Documents/Work in the second panel.
5. Press Tab to return to the first panel.
6. Select report.pdf and press Ctrl+C.
7. Press Tab to switch to the second panel.
8. Press Ctrl+V to paste the file.

Press w to close the focused panel when you are done. You can work with multiple panels, although the practical layout depends on the space available in your terminal.

How to Search and Show Hidden Files

Press / to open the search bar. As you type, Superfile dynamically displays matching results from the current directory. Press Esc or Ctrl+C to leave the search bar. For filesystem searches beyond Superfile’s current-directory search, you can run appropriate shell tools from the command execution bar.

Press . to toggle hidden files. Hidden files begin with a dot on Unix-like systems. This includes .gitignore, .env, .bashrc, and directories like .git/ and .ssh/. This toggle is instant and does not require restarting Superfile.

How to Preview and Open Files

Press f to toggle the preview panel. It shows the contents of the selected file without opening a full editor. Text files, source code, and configuration files are displayed with basic syntax highlighting. Binary files show a summary indicating they are not text. The preview is read-only.

Press m to focus the metadata panel and inspect information about the currently selected item. The displayed metadata updates as you navigate between files and directories.

To edit a file, select it and press e. Superfile first uses the editor option in config.toml when it is configured. If that option is blank, Superfile uses the EDITOR environment variable. If neither specifies an editor, the documented defaults are nano on Linux and macOS and notepad on Windows.

Press Shift+E to open the current directory with the configured directory editor. Superfile provides a separate dir_editor configuration option for this action. The selected editor must support opening a directory for the action to work correctly.

How to Configure Superfile

Superfile stores configuration in platform-specific directories. You can discover the exact paths by running:

spf pl

This prints all relevant file locations for your current platform.

OS	Configuration Path
Linux	~/.config/superfile/
macOS	~/Library/Application Support/superfile/
Windows	%LOCALAPPDATA%\superfile\

The main files are config.toml for appearance and behavior, and hotkeys.toml for keyboard mappings. Both are created automatically on first launch.

Disable Icons If You Do Not Have a Nerd Font

Open config.toml and set:

nerdfont = false

Set Your Preferred Editor

In config.toml, set:

editor = "nvim"

Replace nvim with your preferred editor executable name. The editor configuration option takes priority over the EDITOR environment variable. If the configuration option is left blank, you can set EDITOR in your shell environment instead:

export EDITOR="nvim"

Customize Hotkeys

Open hotkeys.toml. Each action has an array of keys. For example:

list_down = ["down", "j"]
list_up = ["up", "k"]
copy_items = ["ctrl+c"]

Add or remove keys from the array to match your preferences. You can load a custom hotkey file at launch with --hotkey-file /path/to/hotkeys.toml.

For advanced configuration options, see the Complete Superfile Guide.

How to Use Superfile Over SSH

Superfile works over SSH because it requires only a terminal. Connect to your remote server, install Superfile on that server using the Linux installation method, and run spf from the remote shell.

ssh [email protected]
cd ~/files
spf

Your local terminal emulator displays the characters that the remote Superfile process sends over the SSH connection. Superfile must be installed on the remote machine. Installing it on your local laptop does not let you browse a remote server unless you also install it there.

Superfile inherits the permissions of the user who launches it. Do not routinely run sudo spf as your default workflow. A mistyped permanent delete as root can damage system directories. Use a restricted user account for routine browsing and elevate privileges only for specific administrative tasks.

If you use WSL, you can install Superfile inside the WSL distribution using the Linux installation method and run it from the WSL shell. This is an alternative to Superfile’s native Windows installation methods, not a requirement for Windows users.

Superfile Keyboard Shortcuts Cheat Sheet

Task	Key	What Happens
Move up	Up or k	Cursor moves up one item
Move down	Down or j	Cursor moves down one item
Open directory/file	Enter, Right, or l	Enters directory or opens file
Parent directory	h, Left, or Backspace	Goes to parent folder
Quit	q or Esc	Exits Superfile
Search	/	Filters current directory by filename
Toggle hidden files	.	Shows or hides dotfiles
Toggle preview	f	Shows or hides file preview panel
Focus metadata	m	Moves focus to the metadata panel
New panel	n	Creates a new file panel
Close panel	w	Closes the focused panel
Switch panel	Tab or L (Shift+L)	Moves focus to the next file panel
Create file/folder	Ctrl+N	Prompts for name; end with / for folder
Rename	Ctrl+R	Inline rename of selected item
Copy	Ctrl+C	Copies selected item to clipboard
Cut	Ctrl+X	Cuts selected item to clipboard
Paste	Ctrl+V or Ctrl+W	Pastes clipboard into current directory
Delete (trash)	Ctrl+D or Delete	Sends to trash where available
Permanent delete	D (Shift+D)	Permanently deletes selected items instead of using the normal trash workflow
Select mode	v	Toggles multi-select mode
Select all	Shift+A	Selects all items in current panel
Open in editor	e	Opens the selected file with the configured/default editor
Open directory in editor	Shift+E	Opens current directory in editor
Command bar	:	Runs a shell command without quitting
Copy path	Ctrl+P	Copies file path to clipboard
Compress	Ctrl+A	Creates a ZIP archive of selected item
Extract	Ctrl+E	Extracts a selected archive
Zoxide jump	z	Opens zoxide directory navigation

Troubleshooting Superfile

spf Command Not Found

If running spf returns a command not found error, the binary is not in your PATH. On Linux, check ~/.local/bin/. Add it to your PATH in your shell profile. On Windows, restart your terminal after installation. On macOS with Homebrew, ensure Homebrew’s bin directory is in your PATH.

Icons Appear as Squares or Question Marks

Your terminal font does not include Nerd Font glyphs. Either install a Nerd Font and set your terminal to use it, or disable icons in config.toml by setting nerdfont = false.

Permission Denied

Superfile does not bypass filesystem permissions. If your user cannot access a file, neither can Superfile. Check permissions with ls -lah. Do not run sudo spf as a workaround unless you understand the risks.

Preview Does Not Work

Preview behavior depends on the file type and terminal capabilities. Superfile can use the Kitty graphics protocol for supported terminals such as Kitty, WezTerm, and Ghostty, while unsupported terminals fall back to an ANSI-based preview. If image previews are not rendered as expected, check your terminal’s capabilities and Superfile’s image-preview configuration.

Interface Rendering Looks Incorrect

If Superfile’s interface renders incorrectly, first check the terminal environment rather than assuming the operating system is unsupported. The official troubleshooting guidance recommends using a UTF-8 locale and, where appropriate, setting RUNEWIDTH_EASTASIAN=0. On Windows shells where it is applicable, chcp 65001 can also help with character rendering.

Configuration Changes Are Not Applying

Superfile reads configuration at startup. After editing config.toml or hotkeys.toml, quit Superfile with q and relaunch it with spf. Changes do not take effect while Superfile is running.

FAQ

Next Steps

You now have Superfile installed and know the essential navigation, file operations, panel management, and configuration. For deeper topics such as architecture, advanced features, platform analysis, alternatives, and extended customization, see the Complete Superfile Guide.

---

Sources

[1] superfile official documentation: superfile.dev

[2] superfile GitHub repository: github.com/yorukot/superfile