# How to Troubleshoot Superfile Installation Issues: A Complete Guide

> Troubleshoot Superfile installation issues by verifying OS compatibility, overriding environment variables, or building from source. Resolve architecture mismatches, network restrictions, and permission errors with this guide.

- Repository: [Yorukot/superfile](https://github.com/yorukot/superfile)
- Tags: how-to-guide
- Published: 2026-07-29

---

**Most Superfile installation failures stem from architecture mismatches, network restrictions, or permission errors during the execution of the official install script, which can be resolved by verifying OS compatibility, overriding environment variables, or building from source.**

Superfile is a modern terminal file manager developed by the open-source repository yorukot/superfile. The project distributes a self-contained Bash installer at [`website/public/install.sh`](https://github.com/yorukot/superfile/blob/main/website/public/install.sh) that automates OS detection, binary downloads, and PATH configuration, but environmental constraints often trigger failures during this process. Understanding the installer's internal logic allows you to diagnose whether the issue lies in platform support, GitHub API rate limits, or local filesystem permissions.

## Understanding the Superfile Installer Logic

The installation script located at [`website/public/install.sh`](https://github.com/yorukot/superfile/blob/main/website/public/install.sh) executes a deterministic sequence to deploy the `spf` binary. It first detects your platform using `uname -s` and `uname -m` to map to `linux`/`darwin` and `amd64`/`arm64` respectively. The script then queries the GitHub releases API to determine the latest version (or respects the `SPF_INSTALL_VERSION` environment variable), constructs a download URL, and fetches the tarball using `curl` or `wget`.

After downloading, the script attempts to move the binary to `/usr/local/bin/spf` using `sudo`. If this permission elevation fails, it automatically falls back to installing in `~/.local/bin` and attempts to update your shell's `PATH` configuration based on the `$SHELL` environment variable. Finally, it cleans up the temporary directory created during extraction.

## Troubleshooting Common Installation Errors

### "Unsupported architecture" Detection Failure

If you encounter an "Unsupported architecture" error during execution, the script failed to map your CPU type to the supported `amd64` or `arm64` binaries. In [`website/public/install.sh`](https://github.com/yorukot/superfile/blob/main/website/public/install.sh) around line 65-70, the script evaluates `uname -m` and exits if the result does not match expected values.

**Fix:** Manually override the architecture detection by exporting the correct variable before running the installer:

```bash
export ARCH=arm64
bash -c "$(curl -sLo- https://superfile.dev/install.sh)"

```

### "Failed to fetch latest version" Network Errors

When the script cannot retrieve release metadata from `https://api.github.com/repos/yorukot/superfile/releases/latest` (line 41-42), it typically indicates GitHub API rate limiting or corporate network restrictions blocking the endpoint.

**Fix:** Bypass rate limits by using a personal access token or specifying the version manually:

```bash
export GITHUB_TOKEN=your_token_here

# Or skip the API call entirely

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

```

### Permission Denied During Binary Installation

The installer's fallback logic at line 101 attempts `sudo mv ./spf /usr/local/bin/` before falling back to `~/.local/bin`. If you see "Permission denied" and the script cannot elevate privileges, the binary remains in the temporary directory.

**Fix:** Force a local user installation and manually update your PATH:

```bash
bash -c "$(curl -sLo- https://superfile.dev/install.sh)"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

```

### SPF Command Not Found After Installation

This occurs when the installer cannot identify your shell to modify the appropriate rc file (`~/.bashrc`, `~/.zshrc`, etc.), or when a stale binary exists earlier in your PATH.

**Fix:** Verify the installation location and check for conflicting binaries:

```bash
type -a spf
which -a spf

# Remove stale versions

rm ~/.local/bin/spf
sudo rm /usr/local/bin/spf

# Reinstall

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

```

## Step-by-Step Diagnostic Workflow

Follow this sequence to isolate the failure point in [`website/public/install.sh`](https://github.com/yorukot/superfile/blob/main/website/public/install.sh):

1. **Verify network connectivity:** Run `curl -I https://superfile.dev/install.sh` to ensure you can reach the installer.

2. **Check platform compatibility:** Execute `uname -s` (should return `Linux` or `Darwin`) and `uname -m` (should return `x86_64` mapped to `amd64` or `arm64`). Exotic architectures like `s390x` or `riscv64` are not supported by pre-built binaries.

3. **Validate GitHub API access:** Test `curl https://api.github.com/repos/yorukot/superfile/releases/latest` to confirm you can query release data without rate-limiting.

4. **Enable verbose debugging:** Trace the script execution to identify the exact failure line:

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

```

5. **Inspect extraction results:** If the download succeeds but extraction fails, verify `tar` is installed and the temporary directory is writable. The script uses `mktemp -d` to create a staging area before moving the binary.

6. **Confirm PATH configuration:** After installation, check if `~/.local/bin` appears in your `$PATH` variable when using `echo $PATH`.

## Alternative Installation Methods

If the Bash installer consistently fails, use these platform-native alternatives that bypass the [`install.sh`](https://github.com/yorukot/superfile/blob/main/install.sh) logic entirely:

- **Homebrew (macOS/Linux):** `brew install superfile` handles dependencies and updates automatically.
- **Winget (Windows):** `winget install --id yorukot.superfile` provides native Windows package management.
- **Scoop (Windows):** `scoop install superfile` offers a lightweight alternative to Winget.
- **PowerShell Script:** Windows users can run `Invoke-Expression` against `https://superfile.dev/install.ps1` instead of the Bash script.

## Building Superfile from Source

When no pre-built binary matches your platform (common for BSD systems or uncommon Linux architectures), compile the binary locally using the repository's build script:

```bash
git clone https://github.com/yorukot/superfile.git --depth=1
cd superfile
./build.sh
sudo mv ./bin/spf /usr/local/bin/
chmod +x /usr/local/bin/spf

```

The [`build.sh`](https://github.com/yorukot/superfile/blob/main/build.sh) script orchestrates the Go compilation process, requiring Go 1.22 or later. The entry point [`main.go`](https://github.com/yorukot/superfile/blob/main/main.go) initializes the terminal interface, while [`src/internal/common/load_config.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/load_config.go) handles post-installation configuration loading.

## Summary

- The [`website/public/install.sh`](https://github.com/yorukot/superfile/blob/main/website/public/install.sh) script requires `Linux` or `Darwin` OS with `amd64` or `arm64` architecture; exotic CPUs require building from source using [`build.sh`](https://github.com/yorukot/superfile/blob/main/build.sh).
- Network errors during version fetching usually indicate GitHub API rate limits, resolvable by setting `SPF_INSTALL_VERSION` or `GITHUB_TOKEN`.
- Permission failures trigger an automatic fallback to `~/.local/bin`, but you must manually add this directory to your PATH if the script cannot detect your shell.
- Stale binaries in `/usr/local/bin` or `~/.local/bin` can cause version mismatches; use [`website/public/uninstall.sh`](https://github.com/yorukot/superfile/blob/main/website/public/uninstall.sh) or manual removal to clean old installations.
- Alternative package managers (Homebrew, Winget, Scoop) provide reliable workarounds when the standalone installer fails.

## Frequently Asked Questions

### Why does the Superfile installer report "Unsupported architecture" on my Raspberry Pi?

Raspberry Pi devices often report `armv7l` or `aarch64` via `uname -m`, which maps to `arm64` in the installer logic at line 65 of [`website/public/install.sh`](https://github.com/yorukot/superfile/blob/main/website/public/install.sh). However, older Pis using `armv6` or `armv7` without 64-bit support are not supported by pre-built binaries. You must either export `ARCH=arm64` to force the download (if running a 64-bit OS) or build from source using the [`build.sh`](https://github.com/yorukot/superfile/blob/main/build.sh) script.

### How do I fix "Failed to fetch latest version" errors when behind a corporate firewall?

The installer queries `https://api.github.com/repos/yorukot/superfile/releases/latest` using `curl` (line 42). Corporate proxies often block this endpoint or impose strict rate limits. Set `SPF_INSTALL_VERSION` to a specific tag (e.g., `export SPF_INSTALL_VERSION=1.1.8`) to skip the API call entirely, or configure `curl` to use a proxy via the `https_proxy` environment variable.

### Can I install Superfile without root or sudo privileges?

Yes. The installer automatically falls back to `~/.local/bin` when `sudo mv /usr/local/bin/spf` fails (line 101). However, you must ensure `~/.local/bin` exists and is present in your `$PATH`. After installation, add `export PATH="$HOME/.local/bin:$PATH"` to your shell configuration file (`~/.bashrc`, `~/.zshrc`, etc.) and reload the configuration with `source ~/.bashrc`.

### Why does `spf --version` show an old version after reinstalling?

Multiple `spf` binaries likely exist in your PATH. Run `which -a spf` to locate all instances. The installer may have placed the new version in `~/.local/bin` while an older copy remains in `/usr/local/bin`, which typically precedes local paths in shell initialization. Remove the stale binary from `/usr/local/bin` using `sudo rm /usr/local/bin/spf`, or adjust your PATH priority so that `~/.local/bin` precedes `/usr/local/bin`.