Guide · Open source

How to use superfile: install, launch spf and customize

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

superfile is a free, open-source file manager that runs inside a terminal window. You browse, open and manage folders and files with the keyboard, and it is started with the command spf. This guide shows you how to install it, launch it, and set it up to suit your workflow.

superfileyorukot/superfile · ★ 24k · MIT Install options & downloads

Quick start

1Install superfile. On macOS or Linux, run the install script from the README after reviewing it. On Windows, use the Winget command.
2Launch spf. Type spf in a terminal window to start the file manager.
3Learn the hotkeys. Read the hotkey wiki to learn the keyboard controls. Vim and Neovim users should switch to the vim-style config.
4Customize. Apply a theme or plugin from the superfile.dev wiki pages if you want to change how it looks or behaves.
5Adjust update checks. Set auto_check_update to false in the config if you do not want the update prompt.

Install superfile on macOS, Linux or Windows

On macOS and Linux, the README gives a one-line install command that runs a script from superfile.dev. The README suggests reviewing the script first, and links to install.sh so you can read it before running anything.

On Windows, the README lists a Winget command. It also lists PowerShell and Scoop options. Windows support is not fully supported yet, according to the README.

macOS and Linux: run the install script from the README
Windows: use Winget, PowerShell, or Scoop
Other methods: see the installation page linked from the README

winget install --id yorukot.superfile

Build superfile from source

If you want to build it yourself, the README lists Go (golang) as the requirement. You clone the repository, enter the directory, and run the build script on macOS or Linux.

After building, the README says to add the binary to your PATH. On macOS or Linux it gives an example of moving bin/spf to /usr/local/bin. On Windows, it says to add the repo's bin directory to your PATH through System Environment Variables.

Requirement: golang
Run ./build.sh on macOS or Linux
On Windows, run go build -o bin/spf.exe

cd superfile
./build.sh
sudo mv ./bin/spf /usr/local/bin

Start superfile and open your first folder

Once installed, start superfile by typing spf in your terminal. The README gives this as the only start command. It runs the file manager in the current terminal window.

The README points to a tutorial on the superfile website for a brief walkthrough of how to move around. The hotkeys are documented on the hotkey wiki page.

Type spf in a terminal to launch
Use the hotkey wiki to learn the keyboard controls

spf

Set up hotkeys for vim or Neovim

The README includes a warning: if you are a vim or Neovim user, change your default hotkeys config to the vim version. The vim-style hotkeys are documented on the hotkey wiki page linked in the README.

Hotkeys are one of the three customization areas the README points to, along with themes and plugins.

Vim and Neovim users should switch to the vim-style hotkeys
Hotkey details are on the superfile.dev hotkey wiki

Customize themes, plugins and settings

superfile supports custom themes, plugins and hotkeys. The README links to separate wiki pages for each: the plugin list, the custom theme guide, and the custom hotkeys guide.

The README also describes an auto update check. superfile fetches the latest released version from GitHub, at most once every 24 hours, and shows a prompt if a newer version exists. To turn this off, set auto_check_update to false in the superfile config file. The config wiki explains the settings.

Plugins: see the plugin list on superfile.dev
Themes: see the custom theme guide
Auto update check: set auto_check_update to false in the config

Uninstall superfile and remove its data

On macOS and Linux, the README provides an uninstall script. It removes the spf binary from /usr/local/bin or ~/.local/bin, and also deletes your config and data folders. These are ~/.config/superfile, ~/.local/share/superfile and ~/.local/state/superfile, and on macOS ~/Library/Application Support/superfile.

On Windows, the uninstall script does not remove your config and data folder. You must delete %LOCALAPPDATA%\superfile yourself. If you installed with a package manager, the README says to run spf pl first to find where those folders are.

macOS and Linux: the script deletes config and data folders
Windows: delete %LOCALAPPDATA%\superfile manually
Package manager installs: run spf pl to find folder locations

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

What people use it for

Browsing and managing folders and files from a terminal session without switching to a graphical app
Using a visual file browser while working in the terminal on Linux or macOS
Using vim-style hotkeys if you already navigate with Vim or Neovim
Customizing the look with themes and extending it with plugins

Frequently asked questions

How do I install superfile?

On macOS and Linux, run the install command from the README, which downloads a script from superfile.dev. On Windows, run winget install --id yorukot.superfile. The README suggests reviewing the install script before running it.

How do I start superfile?

Type spf in your terminal. The command launches the file manager in that terminal window.

Is superfile free and open source?

Yes. The project is released under the MIT licence, according to the README, and its source code is on GitHub.

What operating systems does superfile support?

The README lists Linux and macOS as supported. Windows is listed as not fully supported yet.

How do I fix superfile problems or uninstall it?

The README links to a troubleshooting page on superfile.dev for common fixes. To uninstall on macOS or Linux, run the uninstall script from the README, which also deletes config and data folders.

What are alternatives to superfile?

The README lists ranger, nnn, yazi and lf as comparable projects. Pick one based on which keys, themes and features you prefer.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

superfile suits people who live in the terminal and want a modern, visual file browser there, especially on Linux or macOS. If you want a graphical file manager with windows and mouse menus, or you need fully stable Windows support, pick a different tool.

Install options & downloads