How to Install Waterfox on Debian (13, 12, 11)

Waterfox is built on Firefox but strips out telemetry, routes DNS-over-HTTPS through privacy-respecting relays, and blocks cookie banners by default. It keeps full compatibility with Firefox extensions, so you get the privacy without giving up your favorite add-ons. To install Waterfox browser on Debian, Flatpak is the recommended approach for most users.

Previous versions of this guide documented a third-party APT repository (the OpenSUSE Build Service maintained by hawkeye116477). That repository is no longer maintained and has been removed. Waterfox is not available as a native .deb package; the Flatpak and tarball methods below are the currently supported options.

Install Waterfox Browser on Debian

Waterfox supports two installation methods on Debian. Flatpak handles updates automatically and keeps Waterfox sandboxed from the rest of your system, while the tarball method gives you a portable installation you can drop into any directory.

Method	Channel	Version	Updates	Best For
Flatpak	Flathub	Latest stable	Automatic via flatpak update	Users wanting sandboxed installation with automatic updates
Tarball	GitHub Releases	Latest release	Manual (re-download or use update script)	Users wanting portable installation or immediate access to new releases

For most users, the Flatpak method is recommended. It updates itself, runs sandboxed, and works the same way on every Debian version. Go with the tarball if you need a portable installation or want new releases the moment they ship on GitHub, before Flathub catches up.

Update Debian Before Waterfox Installation

Update your system’s package index and upgrade existing packages to ensure you have the latest security patches:

sudo apt update && sudo apt upgrade

All commands in this guide require sudo privileges. If your user account is not yet in the sudoers file, see how to add a user to sudoers on Debian.

Method 1: Install Waterfox on Debian via Flatpak and Flathub (Recommended)

Flatpak keeps Waterfox isolated from your system through automatic sandboxing while maintaining access to network, audio, and display resources. The Waterfox Flatpak is officially published on Flathub.

Set Up Flatpak and Flathub on Debian

If Flatpak is not already configured on your system, install it and add the Flathub repository. For detailed instructions, see our guide on Flatpak on Debian.

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

After adding Flathub for the first time, you may need to log out and back in (or reboot) for the Flatpak integration to work properly with your desktop environment.

Install Waterfox from Flathub

sudo flatpak install flathub net.waterfox.waterfox -y

The first Flatpak installation may take longer as it downloads shared runtime libraries alongside Waterfox itself.

Verify Waterfox Flatpak Installation

Confirm Waterfox is installed by listing your Flatpak applications:

flatpak list --app | grep -i waterfox

Expected output:

Waterfox	net.waterfox.waterfox	6.6.x	stable	system

Method 2: Install Waterfox on Debian via Tarball (Portable)

The tarball method provides a portable Waterfox installation that you can place in any directory. It uses the GitHub API to automatically detect the latest version, but unlike Flatpak, tarball installations do not update automatically.

Install Waterfox Tarball Prerequisites

Install the packages needed to download and extract the Waterfox tarball. The curl package handles downloads, while tar and bzip2 handle extraction:

sudo apt install curl tar bzip2 -y

Download the Latest Waterfox Tarball

Query the GitHub API to get the latest Waterfox version, then download the corresponding Linux tarball from the official CDN:

LATEST_VERSION=$(curl -s https://api.github.com/repos/BrowserWorks/Waterfox/releases/latest | grep -oP '"tag_name": "\K[^"]+')
echo "Latest version: $LATEST_VERSION"

DOWNLOAD_URL="https://cdn1.waterfox.net/waterfox/releases/${LATEST_VERSION}/Linux_x86_64/waterfox-${LATEST_VERSION}.tar.bz2"
curl -Lo waterfox-${LATEST_VERSION}.tar.bz2 "$DOWNLOAD_URL"

Expected output showing the download progress:

Latest version: 6.x.x
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   94M  100   94M    0     0  15.2M      0  0:00:06  0:00:06 --:--:-- 17.8M

Extract Waterfox to System Directory

Extract the tarball to /opt/waterfox where system-wide applications are typically installed:

sudo tar -xjf waterfox-${LATEST_VERSION}.tar.bz2 -C /opt

Verify the extraction by checking the Waterfox directory:

ls -lh /opt/waterfox/waterfox
du -sh /opt/waterfox/

Expected output:

-rwxr-xr-x 1 root root 770K Feb 24 23:18 /opt/waterfox/waterfox
298M	/opt/waterfox/

Create Waterfox Symbolic Link for System-Wide Access

Create a symbolic link in /usr/local/bin so you can run the waterfox command from anywhere:

sudo ln -sf /opt/waterfox/waterfox /usr/local/bin/waterfox

Verify the link and check the installed version:

which waterfox
waterfox --version

Expected output:

/usr/local/bin/waterfox
BrowserWorks Waterfox 6.x.x

Create Waterfox Desktop Entry for Application Menu

Create a desktop entry file so Waterfox appears in your application menu:

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

Update the desktop database to register the new application:

sudo update-desktop-database

Launch Waterfox on Debian

Launch Waterfox from Terminal

Tarball installation:

waterfox

Flatpak installation:

flatpak run net.waterfox.waterfox

Launch Waterfox from Applications Menu

Both installation methods create a desktop entry. To launch Waterfox graphically:

1. Open your desktop’s Activities view or application menu.
2. Search for “Waterfox” in the search bar.
3. Click the Waterfox icon to launch the browser.

Manage Waterfox on Debian

Update Waterfox

How you update Waterfox depends on which method you used to install it.

For Flatpak installation:

Flatpak periodically checks Flathub for new releases in the background, so your desktop environment’s software center may show update notifications automatically. To update manually:

sudo flatpak update net.waterfox.waterfox

For tarball installation (manual method):

Tarball installations do not update automatically. Download the latest version and extract it to /opt to replace the existing installation:

LATEST_VERSION=$(curl -s https://api.github.com/repos/BrowserWorks/Waterfox/releases/latest | grep -oP '"tag_name": "\K[^"]+')
DOWNLOAD_URL="https://cdn1.waterfox.net/waterfox/releases/${LATEST_VERSION}/Linux_x86_64/waterfox-${LATEST_VERSION}.tar.bz2"
curl -Lo waterfox-${LATEST_VERSION}.tar.bz2 "$DOWNLOAD_URL"
sudo tar -xjf waterfox-${LATEST_VERSION}.tar.bz2 -C /opt

The extraction automatically replaces the existing /opt/waterfox directory. Verify the update:

waterfox --version

Expected output:

BrowserWorks Waterfox 6.x.x

For tarball installation (automated script):

Instead of repeating the manual steps each time, you can save a short bash script that handles the entire update process. When you run it, the script queries GitHub for the latest release, compares it against your installed version, and only downloads if a newer version is available.

The following command creates the script at ~/update-waterfox.sh:

cat > ~/update-waterfox.sh << 'EOF'
#!/bin/bash
set -e

## Step 1: Query GitHub API for the latest release tag
echo "Checking for latest Waterfox version..."
LATEST_VERSION=$(curl -s https://api.github.com/repos/BrowserWorks/Waterfox/releases/latest | grep -oP '"tag_name": "\K[^"]+')

if [ -z "$LATEST_VERSION" ]; then
    echo "Error: Failed to fetch latest version from GitHub"
    exit 1
fi

## Step 2: Compare installed version against latest
CURRENT_VERSION=$(waterfox --version 2>/dev/null | grep -oP '\d+\.\d+\.\d+' || echo "Not installed")
echo "Current version: $CURRENT_VERSION"
echo "Latest version: $LATEST_VERSION"

if [ "$CURRENT_VERSION" = "$LATEST_VERSION" ]; then
    echo "Waterfox is already up to date."
    exit 0
fi

## Step 3: Download the new tarball to a temp directory
echo "Downloading Waterfox $LATEST_VERSION..."
DOWNLOAD_URL="https://cdn1.waterfox.net/waterfox/releases/${LATEST_VERSION}/Linux_x86_64/waterfox-${LATEST_VERSION}.tar.bz2"
TEMP_DIR=$(mktemp -d)
cd "$TEMP_DIR"
curl -Lo waterfox.tar.bz2 "$DOWNLOAD_URL"

## Step 4: Extract over the existing /opt/waterfox directory
echo "Extracting to /opt/waterfox..."
sudo tar -xjf waterfox.tar.bz2 -C /opt

## Step 5: Clean up the temp directory
echo "Cleaning up temporary files..."
cd ~
rm -rf "$TEMP_DIR"

echo "Update complete! Waterfox $LATEST_VERSION is now installed."
waterfox --version
EOF

Before you can run the script, mark it as executable with chmod. You only need to do this once:

chmod +x ~/update-waterfox.sh

Now run the script:

~/update-waterfox.sh

Example output when an update is available:

Checking for latest Waterfox version...
Current version: 6.6.8
Latest version: 6.6.9
Downloading Waterfox 6.6.9...
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   94M  100   94M    0     0  15.2M      0  0:00:06  0:00:06 --:--:-- 17.8M
Extracting to /opt/waterfox...
Cleaning up temporary files...
Update complete! Waterfox 6.6.9 is now installed.
BrowserWorks Waterfox 6.6.9

If Waterfox is already on the latest version, the script exits early:

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

The script does not run on a schedule. Run ~/update-waterfox.sh whenever you want to check for a new release.

Import Data from Firefox to Waterfox

Waterfox can import bookmarks, history, and settings from Firefox. If you previously used Firefox on Debian, open Waterfox and navigate to Settings > Import browser data to transfer your data.

Remove Waterfox from Debian

If you decide to remove Waterfox from your system, follow the instructions below that match your installation method.

Remove Flatpak Installation

sudo flatpak uninstall net.waterfox.waterfox

Remove unused Flatpak runtimes:

sudo flatpak uninstall --unused

Verify removal:

flatpak list --app | grep -i waterfox

No output confirms Waterfox has been removed.

Remove Tarball Installation

Delete the Waterfox directory, symbolic link, desktop entry, and update script:

sudo rm -rf /opt/waterfox
sudo rm /usr/local/bin/waterfox
sudo rm /usr/share/applications/waterfox.desktop
rm -f ~/update-waterfox.sh
sudo update-desktop-database

Verify complete removal by checking that the which command no longer finds Waterfox:

which waterfox

Expected output confirming removal:

which: no waterfox in (/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin)

Remove Waterfox User Data (Optional)

Warning: The following commands permanently delete your Waterfox profile data including bookmarks, saved passwords, browsing history, and custom settings. Export any data you want to keep before proceeding.

For tarball installations, Waterfox stores user data in your home directory:

rm -rf ~/.waterfox
rm -rf ~/.cache/waterfox

Flatpak installations store user data in a sandboxed location:

rm -rf ~/.var/app/net.waterfox.waterfox

Troubleshoot Waterfox on Debian

Waterfox Crashes on Launch

If Waterfox crashes immediately after launching, start it in safe mode from the terminal to see error messages. Safe mode disables extensions and custom themes, which helps identify if an extension causes the crash.

Tarball installation:

waterfox --safe-mode

Flatpak installation:

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

If safe mode works, disable extensions one by one to find the problematic one.

Waterfox Not Found After Tarball Install

If you see command not found when running waterfox after a tarball installation, the symbolic link may be missing or broken. Re-create it:

sudo ln -sf /opt/waterfox/waterfox /usr/local/bin/waterfox
waterfox --version

Expected output:

BrowserWorks Waterfox 6.x.x

Flatpak Permission Errors

If Waterfox cannot access specific directories or features when installed via Flatpak, grant the required permissions using flatpak override. For example, to allow access to a custom downloads directory:

sudo flatpak override net.waterfox.waterfox --filesystem=/path/to/directory

To view current permissions:

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

Frequently Asked Questions

Conclusion

Waterfox is running on your Debian system with telemetry disabled, DNS-over-HTTPS active, and tracking protection enabled out of the box. If you went with Flatpak, updates happen automatically through Flathub. Tarball users should run the update script periodically to stay current. Either way, every Firefox extension works without modification. For additional browser options, consider Google Chrome on Debian or Brave browser on Debian.