How to Install Waterfox on Debian

Waterfox is a privacy-focused web browser built on the Mozilla Firefox codebase that prioritizes user control and customization. Unlike mainstream browsers, Waterfox disables telemetry and data collection by default, routes DNS-over-HTTPS through privacy-respecting relays, and includes built-in cookie banner rejection. Whether you want a Firefox alternative without tracking, need a browser that respects your privacy settings, or prefer deeper customization options, Waterfox delivers these features while maintaining compatibility with Firefox extensions. By the end of this guide, you will have Waterfox installed and running on your Debian system using either Flatpak or a portable tarball installation.

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 from this guide. The Flatpak and tarball methods documented below are the currently supported options for installing Waterfox on Debian.

Choose Your Waterfox Installation Method

Waterfox supports two installation methods on Debian: Flatpak from Flathub and direct tarball installation from the official GitHub releases. Flatpak provides containerized installation with automatic sandboxing and updates, while the tarball method offers a portable installation that you can place anywhere on your system. Choose Flatpak if you prefer automatic updates and sandboxed applications, or the tarball method if you need a portable installation or want immediate access to the latest releases.

Method	Channel	Version	Updates	Best For
Flatpak	Flathub	Latest stable	Automatic via flatpak update	Users wanting containerized installation with sandboxing and automatic updates
Tarball	GitHub Releases	Latest release	Manual (re-download tarball or use update script)	Users wanting portable installation or testing latest releases immediately

For most users, the Flatpak method is recommended because it provides automatic security updates, sandboxed operation, and works identically across all Debian versions. The tarball method works best when you need a portable installation, want to place Waterfox in a custom location, or need immediate access to new releases before they appear on Flathub. If you need a more mainstream browser alongside Waterfox, consider installing Google Chrome on Debian as well.

Update Debian Before Installation

Before installing Waterfox, update your system’s package index and upgrade existing packages. This ensures you have the latest security patches and prevents potential dependency conflicts during installation:

sudo apt update && sudo apt upgrade

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

Flatpak provides containerized deployment with automatic sandboxing, keeping Waterfox isolated from your system while maintaining access to necessary resources such as network, audio, and display. This isolation improves security because Waterfox runs with restricted access to your filesystem by default. The Waterfox Flatpak is officially published on Flathub.

Set Up Flatpak and Flathub

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

Quick setup commands:

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

With Flatpak configured, install Waterfox from Flathub:

sudo flatpak install flathub net.waterfox.waterfox -y

Flatpak then downloads the application and any required runtimes. Note that the first installation may take longer as it downloads shared runtime libraries.

Verify Flatpak Installation

To confirm Waterfox is installed, list your Flatpak applications:

flatpak list --app | grep -i waterfox

Expected output:

Waterfox    net.waterfox.waterfox    stable    system

Method 2: Install Waterfox via Tarball (Portable)

For those seeking maximum flexibility, the tarball method provides a portable installation of Waterfox that you can install to any directory on your system. This method uses the GitHub API to automatically detect and download the latest version, making it easy to stay current with releases. However, tarball installations do not update automatically; you must manually download new versions or use the provided update script.

Install Prerequisites for Tarball Extraction

First, install the packages needed to download and extract the Waterfox tarball. The curl package downloads files from the web, while tar and bzip2 handle tarball extraction:

sudo apt install curl tar bzip2 -y

Download Latest Waterfox Tarball

Next, query the GitHub API to get the latest Waterfox version, then download the corresponding Linux tarball from the official CDN. The following commands automatically detect the current version and construct the download URL:

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 82.4M  100 82.4M    0     0  15.2M      0  0:00:05  0:00:05 --:--:-- 17.8M

Extract Waterfox to System Directory

Once the download completes, extract the tarball to /opt/waterfox where system-wide applications are typically installed. This location makes Waterfox accessible to all users on the system:

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

Verify the installation by checking the Waterfox directory contents:

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

Expected output confirming the installation:

-rwxr-xr-x 1 root root 730K Dec  9 15:43 /opt/waterfox/waterfox
297M    /opt/waterfox/

Create Symbolic Link for System-Wide Access

After extraction, create a symbolic link in /usr/local/bin so you can launch Waterfox from anywhere without specifying the full path. This makes the waterfox command available system-wide:

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

Verify the symbolic link creation and test the command:

which waterfox
waterfox --version

Expected output showing successful installation:

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

Create Desktop Entry for Application Menu

Finally, create a desktop entry file so Waterfox appears in your application menu and launcher. This allows you to launch Waterfox through your desktop environment’s interface:

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

After creating the desktop entry, update the desktop database to register the new application:

sudo update-desktop-database

After creating the desktop entry, Waterfox will appear in your application menu alongside other installed browsers.

Launch Waterfox

After installation, you can launch Waterfox using either the terminal or your desktop’s application menu.

Launch from Terminal

Launch Waterfox directly from the terminal using the appropriate command for your installation method.

Tarball installation:

waterfox

Flatpak installation:

flatpak run net.waterfox.waterfox

Launch 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

Update Waterfox

Waterfox receives regular updates with security patches and new features. The update method depends on how you installed the browser.

For Flatpak installation:

For Waterfox installed via Flatpak, update all Flatpak applications with the following command. Flatpak periodically checks Flathub for new releases in the background, so you typically receive update notifications through your desktop environment’s software center as well:

sudo flatpak update net.waterfox.waterfox

For tarball installation (manual method):

Unlike Flatpak, tarball installations do not update automatically. To update Waterfox installed from a tarball, download the latest version using the same commands from the installation section, then 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 with the new version. Afterward, verify the update succeeded by checking the version:

waterfox --version

For tarball installation (automated script):

For easier updates, create a bash script that automates the download and installation process. Save the following script to ~/update-waterfox.sh:

Unlike Flatpak installations, tarball deployments require manual intervention to check for and install updates. This script automates version checking and download but still requires you to run it manually. There is no background update mechanism for tarball installations.

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

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"
    exit 1
fi

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

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"

echo "Extracting to /opt/waterfox..."
sudo tar -xjf waterfox.tar.bz2 -C /opt

echo "Cleaning up temporary files..."
cd ~
rm -rf "$TEMP_DIR"

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

Once saved, make the script executable and run it to update Waterfox:

chmod +x ~/update-waterfox.sh
~/update-waterfox.sh

The script checks your current Waterfox version against the latest release, downloads and installs updates only when a new version is available, and automatically cleans up temporary files after installation. Therefore, run this script periodically to keep your tarball installation current.

Remove Waterfox

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

Additionally, to remove unused Flatpak runtimes:

sudo flatpak uninstall --unused

Remove Tarball Installation

To remove a tarball installation, delete the Waterfox directory, remove the symbolic link, delete the desktop entry, and clean up any remaining configuration files:

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

Then, update the desktop database to remove Waterfox from your application menu:

sudo update-desktop-database

Verify complete removal by checking that the command is no longer available:

which waterfox

Expected output confirming removal:

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

Remove 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

In contrast, Flatpak installations store user data in a sandboxed location:

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

Troubleshooting

Waterfox Crashes on Launch

If Waterfox crashes immediately after launching, try starting it from the terminal to see error messages:

waterfox --safe-mode

Safe mode disables extensions and custom themes, which helps identify if an extension causes the crash. If safe mode works, then disable extensions one by one to find the problematic one.

Import Data from Firefox

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.

Conclusion

You now have Waterfox installed on Debian using either the Flatpak or tarball method. Flatpak offers containerized isolation with sandboxing and automatic updates through Flathub, while the tarball method gives you a portable installation with manual update control. Regardless of your installation method, the browser provides privacy-focused defaults including disabled telemetry, DNS-over-HTTPS, and built-in tracking protection while maintaining full Firefox extension compatibility. For Flatpak installations, updates arrive automatically, while tarball installations require periodic manual updates using the provided script or re-downloading the latest release.