How to Install Waterfox on Debian 13, 12 and 11

Firefox extension compatibility is the draw for Debian users who want stronger privacy defaults without giving up the Mozilla add-on ecosystem. To install Waterfox browser on Debian, use Flathub for the easiest update path or the official tarball when you want the newest upstream release as soon as it appears on Waterfox’s CDN.

The older openSUSE Build Service APT repository maintained by hawkeye116477 is no longer maintained. Do not add that repository on new systems; use Flatpak or the official tarball method instead.

Install Waterfox Browser on Debian

Waterfox has two practical install paths on Debian. Flatpak is the low-maintenance choice because Flathub handles app and runtime updates, while the tarball installs Waterfox under /opt/waterfox and relies on a manual or helper-driven update workflow. Both documented Linux methods currently target x86_64 systems; the official tarball also requires a CPU with SSE4.2 support.

Method	Source	Update Behavior	Best For	Trade-offs
Flatpak	Flathub	Updates through flatpak update and desktop software centers	Most desktop users who want the least manual maintenance	The listing is verified, but Flathub currently labels it potentially unsafe because the manifest grants broad desktop permissions
Tarball	Official Waterfox download page and GitHub releases	Manual replacement or the update helper in this article	Users who want the newest upstream release before Flathub catches up	Only x86_64 Linux is published, and you own the update and cleanup path

Choose Flatpak unless you specifically need the tarball. The current Flathub listing is verified and presented under BrowserWorks branding, but its broad filesystem, device, network, audio, print, and display permissions make Flatpak a packaging and update convenience rather than a strict sandbox boundary.

Update Debian Before Installing Waterfox

Refresh APT metadata before adding browser tooling or Flatpak support:

sudo apt update

The install commands use sudo for system package and application-directory changes. If your account cannot use sudo yet, use how to add a user to sudoers on Debian before continuing.

Install Waterfox with Flatpak on Debian

Debian provides the flatpak package in its default repositories, but a minimal desktop or server-style install may not have it yet. Install Flatpak and add Flathub as the system-wide remote:

sudo apt install flatpak
sudo flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

If you want the full Flatpak setup flow first, use Install Flatpak on Debian before returning to the Waterfox app command.

Log out and back in after first-time Flatpak setup if Waterfox does not appear in your desktop menu. The app can still be launched from the terminal while the desktop session refreshes its exported launchers.

Install Waterfox from Flathub:

sudo flatpak install flathub net.waterfox.waterfox

Confirm the installed app ID, source, branch, and system installation scope:

flatpak info net.waterfox.waterfox | grep -E '^[[:space:]]*(ID|Ref|Arch|Branch|Version|Origin|Installation|Runtime):'

Relevant output includes:

ID: net.waterfox.waterfox
Ref: app/net.waterfox.waterfox/x86_64/stable
Branch: stable
Origin: flathub
Installation: system

Install Waterfox with the Official Tarball on Debian

The tarball method installs the upstream Linux x86_64 build under /opt/waterfox. It is useful when GitHub and the Waterfox CDN publish a newer release before the Flathub manifest updates.

Install Tarball Prerequisites

Install the tools used to resolve the latest release, download the archive, verify its SHA512 checksum, extract the tarball, and register the desktop launcher:

sudo apt install curl jq tar bzip2 desktop-file-utils

The download command uses curl, while the reusable update helper later uses jq to parse the GitHub release API instead of scraping JSON with text filters.

Download, Verify, and Install the Tarball

The next block replaces the application files under /opt/waterfox. Close Waterfox first if you already have a tarball install running. Browser profiles, bookmarks, passwords, and cache data live in your home directory and are not stored under /opt/waterfox.

Resolve the latest Waterfox release, download the Linux x86_64 tarball and matching SHA512 file, verify the archive, then move the extracted application into /opt/waterfox:

(
set -e
workdir=$(mktemp -d)
trap 'rm -rf "$workdir"' EXIT
cd "$workdir"

latest_version=$(curl -fsSL https://api.github.com/repos/BrowserWorks/Waterfox/releases/latest | jq -r '.tag_name // empty')
if [ -z "$latest_version" ]; then
  echo "Could not resolve the latest Waterfox release."
  exit 1
fi

archive="waterfox-${latest_version}.tar.bz2"
base_url="https://cdn.waterfox.com/waterfox/releases/${latest_version}/Linux_x86_64"

curl -fL -o "$archive" "${base_url}/${archive}"
curl -fL -o "${archive}.sha512" "${base_url}/${archive}.sha512"
sha512sum -c "${archive}.sha512"
tar -xjf "$archive"
./waterfox/waterfox --version

sudo rm -rf /opt/waterfox
sudo mv waterfox /opt/waterfox
)

After the transfer output, relevant lines include:

waterfox-6.6.13.tar.bz2: OK
BrowserWorks Waterfox 6.6.13

Create the Waterfox Command Link

Add a guarded command link in /usr/local/bin. The guard avoids replacing an unrelated regular file named waterfox:

if [ -e /usr/local/bin/waterfox ] && [ ! -L /usr/local/bin/waterfox ]; then
  printf '%s\n' "/usr/local/bin/waterfox exists and is not a symlink; inspect it before replacing."
else
  sudo ln -sfn /opt/waterfox/waterfox /usr/local/bin/waterfox
fi

Verify that the shell resolves the expected command and Waterfox reports its version:

command -v waterfox
waterfox --version

Relevant output includes:

/usr/local/bin/waterfox
BrowserWorks Waterfox 6.6.13

Create the Waterfox Desktop Entry

Create a desktop entry so Waterfox appears in application menus and can handle common browser URL and HTML MIME types:

sudo tee /usr/share/applications/waterfox.desktop > /dev/null <<'EOF'
[Desktop Entry]
Name=Waterfox
Comment=Privacy-focused web browser
Exec=/opt/waterfox/waterfox %u
Terminal=false
Type=Application
Icon=/opt/waterfox/browser/chrome/icons/default/default128.png
Categories=Network;WebBrowser;
MimeType=text/html;text/xml;application/xhtml+xml;application/xml;application/vnd.mozilla.xul+xml;x-scheme-handler/http;x-scheme-handler/https;
StartupNotify=true
StartupWMClass=Waterfox
EOF

desktop-file-validate /usr/share/applications/waterfox.desktop
sudo update-desktop-database /usr/share/applications

Launch Waterfox on Debian

Launch Waterfox from a terminal when you need to confirm which method is active, or use the desktop menu for normal browsing.

Launch Waterfox from the Terminal

For the tarball method, use the command link created under /usr/local/bin:

waterfox

For the Flatpak method, launch the Flathub app ID directly:

flatpak run net.waterfox.waterfox

Launch Waterfox from the Applications Menu

Both methods provide a desktop launcher. Open your desktop’s Activities view or application menu, search for “Waterfox,” and click the Waterfox icon.

Update or Remove Waterfox on Debian

Use the update and removal commands that match the method you installed. Flatpak owns the Flathub app and runtime updates, while the tarball method owns files under /opt/waterfox, the optional command link, the desktop entry, and the update helper.

Update Waterfox Flatpak

Update the Waterfox Flatpak from Flathub:

sudo flatpak update net.waterfox.waterfox

Update all system-scope Flatpak apps and runtimes when you want the normal Flatpak maintenance pass instead:

sudo flatpak update

Create a Tarball Update Helper

The tarball method does not receive package-manager updates. Save this helper after the tarball installation if you want a repeatable update command with checksum verification and an early no-op path when Waterfox is already current:

cat > ~/update-waterfox.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

log() {
  printf '%s\n' "$*"
}

workdir=$(mktemp -d)
cleanup() {
  rm -rf "$workdir"
}
trap cleanup EXIT

log "Checking for latest Waterfox release..."
latest_version=$(curl -fsSL https://api.github.com/repos/BrowserWorks/Waterfox/releases/latest | jq -r '.tag_name // empty')
if [ -z "$latest_version" ]; then
  log "Could not resolve the latest Waterfox release."
  exit 1
fi

current_output=$(/opt/waterfox/waterfox --version 2>/dev/null || true)
current_version=$(printf '%s\n' "$current_output" | grep -Eo '[0-9]+([.][0-9]+){2,}' | head -n1 || true)
if [ -z "$current_version" ]; then
  current_version="not installed"
fi

log "Current version: $current_version"
log "Latest version: $latest_version"

if [ "$current_version" = "$latest_version" ]; then
  log "Waterfox is already up to date."
  exit 0
fi

archive="waterfox-${latest_version}.tar.bz2"
base_url="https://cdn.waterfox.com/waterfox/releases/${latest_version}/Linux_x86_64"

cd "$workdir"
log "Downloading Waterfox $latest_version..."
curl -fL -o "$archive" "${base_url}/${archive}"
curl -fL -o "${archive}.sha512" "${base_url}/${archive}.sha512"
sha512sum -c "${archive}.sha512"
tar -xjf "$archive"

log "Replacing /opt/waterfox..."
sudo rm -rf /opt/waterfox
sudo mv waterfox /opt/waterfox

log "Waterfox is now updated."
/opt/waterfox/waterfox --version
EOF

chmod +x ~/update-waterfox.sh

Run the helper whenever you want to check for a tarball update:

~/update-waterfox.sh

During an update, the helper verifies the downloaded tarball’s SHA512 file before replacing /opt/waterfox. When Waterfox is already current, it exits before downloading anything.

Checking for latest Waterfox release...
Current version: 6.6.13
Latest version: 6.6.13
Waterfox is already up to date.

Import Firefox Data into Waterfox

Waterfox can import bookmarks, history, and settings from Firefox profiles. If you previously used Firefox on Debian, open Waterfox and use Settings > Import browser data to start the import.

Remove Waterfox Flatpak

Remove the Waterfox Flatpak app:

sudo flatpak uninstall net.waterfox.waterfox

Confirm the system-scope app is gone:

flatpak list --system --app --columns=application | grep -Fx net.waterfox.waterfox || echo "NOT_INSTALLED"

NOT_INSTALLED

Optionally remove unused Flatpak runtimes after reviewing the prompt:

sudo flatpak uninstall --unused

Remove Waterfox Tarball

The next commands remove the tarball-installed application files, the article-created command link when it is a symlink, the desktop entry, and the optional update helper. They do not delete your browser profile data.

if [ -L /usr/local/bin/waterfox ]; then
  sudo rm -f /usr/local/bin/waterfox
fi

sudo rm -rf /opt/waterfox
sudo rm -f /usr/share/applications/waterfox.desktop
rm -f ~/update-waterfox.sh
sudo update-desktop-database /usr/share/applications
hash -r
command -v waterfox || echo "NOT_FOUND"

NOT_FOUND

Remove Waterfox User Data

The next cleanup removes Waterfox profiles, bookmarks, saved passwords, browsing history, sessions, and local settings for your user account. Export anything you need before deleting these paths.

Check for tarball profile and cache paths first:

find "$HOME/.waterfox" "$HOME/.cache/waterfox" -maxdepth 0 -print 2>/dev/null

Remove the tarball profile and cache paths only when you no longer need that data:

rm -rf "$HOME/.waterfox" "$HOME/.cache/waterfox"

For the Flatpak method, check the app-data path:

find "$HOME/.var/app/net.waterfox.waterfox" -maxdepth 0 -print 2>/dev/null

Remove the Flatpak app data only when you no longer need the profile:

rm -rf "$HOME/.var/app/net.waterfox.waterfox"

Troubleshoot Waterfox on Debian

Clean Up the Retired Waterfox APT Repository

Older versions of this article used the hawkeye116477 openSUSE Build Service repository. If that source is still configured, remove the old APT packages first when present:

mapfile -t old_packages < <(dpkg-query -W -f='${binary:Package}\n' waterfox waterfox-g waterfox-classic 2>/dev/null || true)

if [ "${#old_packages[@]}" -gt 0 ]; then
  sudo apt remove "${old_packages[@]}"
else
  echo "No old Waterfox APT packages are installed."
fi

Then remove the source and keyring paths used by the retired repository formats:

sudo rm -f /etc/apt/sources.list.d/waterfox.sources \
  /etc/apt/sources.list.d/home:hawkeye116477:waterfox.list \
  /usr/share/keyrings/waterfox.gpg \
  /etc/apt/trusted.gpg.d/home_hawkeye116477_waterfox.gpg

sudo apt update

Confirm the old OBS source no longer appears as a package candidate source:

apt-cache policy waterfox waterfox-g waterfox-classic | grep -E 'hawkeye116477|download\.opensuse' || echo "OLD_REPOSITORY_REMOVED"

OLD_REPOSITORY_REMOVED

Fix Waterfox Command Not Found After Tarball Install

If the tarball method installed under /opt/waterfox but waterfox is not found in your terminal, check the binary path and recreate the command link with the same non-symlink guard used during installation:

test -x /opt/waterfox/waterfox && /opt/waterfox/waterfox --version

if [ -e /usr/local/bin/waterfox ] && [ ! -L /usr/local/bin/waterfox ]; then
  printf '%s\n' "/usr/local/bin/waterfox exists and is not a symlink; inspect it before replacing."
else
  sudo ln -sfn /opt/waterfox/waterfox /usr/local/bin/waterfox
fi

command -v waterfox

Check Flatpak File Access

Waterfox’s Flatpak permissions already include common user folders such as Downloads, Desktop, Documents, Music, Pictures, and Videos. Inspect the active permissions before adding overrides:

flatpak info --show-permissions net.waterfox.waterfox

If you need to grant one extra folder, use a user-scoped override even when the app is installed system-wide:

mkdir -p "$HOME/Waterfox-share"
flatpak override --user --filesystem="$HOME/Waterfox-share:rw" net.waterfox.waterfox

Remove user overrides when you no longer need them:

flatpak override --user --reset net.waterfox.waterfox

Start Waterfox with Add-ons Disabled

If Waterfox opens and immediately crashes after an extension or theme change, start it with add-ons disabled, then disable the last extension or theme you changed.

For the tarball method:

waterfox --safe-mode

For the Flatpak method:

flatpak run net.waterfox.waterfox --safe-mode

Conclusion

Waterfox is ready on Debian through either Flathub-managed updates or the verified upstream tarball under /opt/waterfox. Keep the update path tied to the method you chose, and clean up the retired OBS repository if it exists on an older system. For another privacy-focused option, compare Brave browser on Debian.