How to Install Waterfox on Ubuntu 26.04, 24.04 and 22.04

Firefox compatibility still matters when you want a browser that keeps the familiar Mozilla base without leaning on Mozilla’s default telemetry choices. If you want to install Waterfox on Ubuntu, the current choices are the verified Flathub package for managed updates or the official Linux tarball for a self-contained install under /opt.

These workflows are scoped to Ubuntu 26.04, 24.04, and 22.04. Waterfox installs from a terminal either way, but the browser still needs an active graphical session when you launch it.

Install Waterfox on Ubuntu

Two supported installation paths are available on Ubuntu. Flatpak is the easier day-to-day choice because updates stay inside Flathub, while the tarball keeps Waterfox in a predictable /opt/waterfox tree that you can update on your own schedule.

Before choosing a method, note that Waterfox does not currently publish an official Ubuntu APT repository, PPA, Snap package, or .deb installer. Older community Open Build Service packaging still exists, but its Waterfox release is stale compared with the current upstream browser, so the install paths here do not treat that repository as a maintained method.

Method	Source	Release Track	Updates	Best For
Flatpak	Flathub app with verified marker	Flathub stable channel	App-specific Flatpak updates	Readers who want Flathub-managed desktop updates
Tarball	Official Waterfox download	Waterfox stable Linux x86_64 tarball	Manual replacement or helper script	Readers who want the official browser tree under /opt

Flatpak is the better default when you want a managed desktop package outside Ubuntu’s APT database. Use the tarball when you prefer the official direct download or you want the browser installed as a self-managed binary under /opt.

Install Waterfox with Flatpak on Ubuntu

Flathub currently marks net.waterfox.waterfox as verified through Waterfox’s website, so it is the simplest managed option on Ubuntu when you want Flatpak updates without relying on a stale community repository.

Ubuntu 26.04, 24.04, and 22.04 do not include Flatpak by default. If flatpak is missing, start with install Flatpak on Ubuntu, then return here.

Enable the Flathub Remote for Waterfox on Ubuntu

Add Flathub at system scope first. The --if-not-exists flag keeps the command rerunnable, and the canonical Flathub descriptor comes from dl.flathub.org.

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

Check that Ubuntu sees Flathub as a system remote before you install Waterfox.

flatpak remotes --columns=name,options | grep -E '^flathub[[:space:]]'

Relevant output includes:

flathub system

Install the Waterfox Flatpak on Ubuntu

Because the remote was added at system scope, keep the install command at system scope too. Using sudo here avoids the deployment failure that appears when a user-level install tries to use a system-level Flathub remote.

sudo flatpak install flathub net.waterfox.waterfox -y

Verify the installed app with the full Flatpak metadata view. The command prints more lines than you usually need, so focus on the package ID, branch, and install scope. The version line changes whenever Flathub publishes a new Waterfox build.

flatpak info net.waterfox.waterfox

Relevant output includes:

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

Install Waterfox from the Official Tarball on Ubuntu

The tarball path uses the official Linux build published through Waterfox’s download page, BrowserWorks release metadata, and the current Waterfox CDN. It is the best fit when you want the direct upstream download and a self-managed install under /opt.

Prepare Ubuntu for the Waterfox Tarball

Refresh Ubuntu’s package metadata first so the prerequisite install pulls current packages.

sudo apt update

These commands use sudo for tasks that need root privileges. If your account is not in the sudoers file yet, follow how to add a new user to sudoers on Ubuntu before continuing.

Install the tools that download and unpack the archive.

sudo apt install -y curl tar bzip2

curl pulls the release metadata and the archive itself, while tar and bzip2 unpack the .tar.bz2 download. If you want a closer look at the download flags, the curl command in Linux guide explains them in more detail.

Fetch the Latest Waterfox Tarball

Save the GitHub release response into a shell variable first, then extract the current tag from that cached response. This avoids relying on grep -P and keeps the lookup portable across Ubuntu 26.04, 24.04, and 22.04.

RELEASE_JSON=$(curl -fsSL https://api.github.com/repos/BrowserWorks/Waterfox/releases/latest)
LATEST_VERSION=$(printf '%s\n' "$RELEASE_JSON" | grep -m1 tag_name | cut -d '"' -f4)
echo "Latest version: $LATEST_VERSION"

The command should print a non-empty version tag. If it prints a blank value, stop and inspect the GitHub response before building the download URL.

Build the direct download URL from that version string, then download the archive. The -f flag makes curl stop on HTTP errors, and -L follows redirects from the current CDN endpoint.

DOWNLOAD_URL="https://cdn.waterfox.com/waterfox/releases/${LATEST_VERSION}/Linux_x86_64/waterfox-${LATEST_VERSION}.tar.bz2"
curl -fLo waterfox-${LATEST_VERSION}.tar.bz2 "$DOWNLOAD_URL"

Confirm that the tarball is on disk before you extract it.

test -s waterfox-${LATEST_VERSION}.tar.bz2 && echo "Downloaded waterfox-${LATEST_VERSION}.tar.bz2"

The check prints the archive name for the version stored in LATEST_VERSION when curl created a non-empty file.

Extract Waterfox Under /opt on Ubuntu

Extract the archive directly into /opt. Waterfox ships with a top-level waterfox directory, so this command lands the browser at /opt/waterfox.

/opt is the better fit for a browser tarball like this because you are unpacking a self-contained upstream application tree with its own bundled files, icons, and launcher assets. Linux distributions and third-party browser packages commonly keep that style of software under /opt because the whole application stays in one predictable directory that is easy to replace or remove later.

/usr/local still matters here, but it is a better home for the launcher than for the full browser tree. Keeping Waterfox under /opt/waterfox and placing only a symlink in /usr/local/bin gives you a normal shell command without scattering Waterfox files across the rest of /usr/local.

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

Check both the main binary and the bundled icon file before you create launchers.

test -x /opt/waterfox/waterfox && echo "Waterfox binary found"
test -f /opt/waterfox/browser/chrome/icons/default/default128.png && echo "Waterfox icon found"

Relevant output includes:

Waterfox binary found
Waterfox icon found

Create a System-Wide Waterfox Launcher on Ubuntu

Link the main Waterfox binary into /usr/local/bin so your shell can find it without the full /opt path.

This split is the usual compromise for upstream tarballs: the application lives intact under /opt, and /usr/local/bin only exposes the launcher on your PATH. That layout is easier to understand later than treating all of /usr/local as the install root for a bundled browser tree.

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

Confirm that the launcher is available in your PATH and that the binary reports the current Waterfox release. Redirecting stderr keeps the output focused on the launcher path and version string.

command -v waterfox
waterfox --version 2>/dev/null

Relevant output includes the launcher path and a Waterfox version line:

/usr/local/bin/waterfox
BrowserWorks Waterfox

Create a Waterfox Desktop Entry on Ubuntu

Write the desktop file directly into /usr/share/applications. Using tee here matters because plain shell redirection would not inherit sudo when writing a root-owned file.

printf '%s\n' \
'[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;' | sudo tee /usr/share/applications/waterfox.desktop > /dev/null

Verify the fields that desktop environments rely on most.

grep -E '^(Name|Exec|Icon)=' /usr/share/applications/waterfox.desktop

Expected output:

Name=Waterfox
Exec=/opt/waterfox/waterfox %u
Icon=/opt/waterfox/browser/chrome/icons/default/default128.png

Launch Waterfox on Ubuntu

Both install methods can be prepared from a terminal, but Waterfox opens as a desktop browser inside your Ubuntu session. Start it from the applications menu or run waterfox in a terminal window inside GNOME, KDE, Cinnamon, or another desktop session.

Launch Waterfox from the Terminal on Ubuntu

Use the command that matches your install method from a terminal inside GNOME, KDE, Cinnamon, or another graphical session.

Tarball install:

waterfox

Flatpak install:

flatpak run net.waterfox.waterfox

Launch Waterfox from the Applications Menu on Ubuntu

Open your desktop launcher, search for Waterfox, and start it like any other browser. The tarball install uses the desktop file created in the tarball section, while the Flatpak build registers its launcher automatically through Flatpak.

Get Started with Waterfox on Ubuntu

Waterfox keeps the familiar Firefox workflow, so your next steps are mostly about privacy tuning and extensions. Review the browser privacy settings after first launch, then add the Firefox extensions you still rely on and decide whether you want Waterfox to import data from another browser profile.

Find Waterfox Profile Data on Ubuntu

Waterfox profile locations depend on the install method. A tarball install normally uses ~/.waterfox for profiles and ~/.cache/waterfox for cache data, while the Flatpak build stores its app data under ~/.var/app/net.waterfox.waterfox.

find "$HOME" -maxdepth 3 \( -path "$HOME/.waterfox" -o -path "$HOME/.cache/waterfox" -o -path "$HOME/.var/app/net.waterfox.waterfox" \) -print 2>/dev/null

Update or Remove Waterfox on Ubuntu

Waterfox updates depend on the path you chose. If you are comparing other browser workflows afterward, install Brave Browser on Ubuntu, install Firefox Beta and Nightly on Ubuntu, or install Vivaldi Browser on Ubuntu for a different mix of package management, browser isolation, and upstream release cadence.

Update Waterfox on Ubuntu

Flatpak handles updates through Flathub, while the tarball install needs a fresh download when a new Waterfox release lands.

Update Waterfox via Flatpak on Ubuntu

Update just the Waterfox Flatpak instead of every installed Flatpak app.

sudo flatpak update net.waterfox.waterfox -y

After the update finishes, rerun flatpak info net.waterfox.waterfox if you want to confirm the new version.

Update the Waterfox Tarball Manually on Ubuntu

The manual update path follows the same release lookup as the original tarball install, but it stages the new browser tree before replacing the current one. Resolve the latest release first, confirm the URL you are about to use, download the archive, and only then replace the files under /opt.

RELEASE_JSON=$(curl -fsSL https://api.github.com/repos/BrowserWorks/Waterfox/releases/latest)
LATEST_VERSION=$(printf '%s\n' "$RELEASE_JSON" | grep -m1 tag_name | cut -d '"' -f4)
DOWNLOAD_URL="https://cdn.waterfox.com/waterfox/releases/${LATEST_VERSION}/Linux_x86_64/waterfox-${LATEST_VERSION}.tar.bz2"
echo "Latest version: $LATEST_VERSION"
echo "Download URL: $DOWNLOAD_URL"

Download the new archive after those values look correct. If the version line is blank, stop and inspect the release response before using the URL.

curl -fLo waterfox-${LATEST_VERSION}.tar.bz2 "$DOWNLOAD_URL"
test -s waterfox-${LATEST_VERSION}.tar.bz2 && echo "Downloaded waterfox-${LATEST_VERSION}.tar.bz2"

Stage the archive in a temporary /opt/waterfox-new directory first. This keeps the current browser tree in place until the new archive has unpacked and the binary exists.

sudo rm -rf /opt/waterfox-new
sudo mkdir -p /opt/waterfox-new
sudo tar -xjf waterfox-${LATEST_VERSION}.tar.bz2 -C /opt/waterfox-new --strip-components=1
sudo test -x /opt/waterfox-new/waterfox && echo "Staged Waterfox update"

Replace the current install only after staging succeeds. The previous tree stays at /opt/waterfox.previous until the new binary reports a version.

sudo rm -rf /opt/waterfox.previous
if sudo test -d /opt/waterfox; then
    sudo mv /opt/waterfox /opt/waterfox.previous
fi
sudo mv /opt/waterfox-new /opt/waterfox
if waterfox --version 2>/dev/null; then
    sudo rm -rf /opt/waterfox.previous
else
    echo "Version check failed; rolling back." >&2
    sudo rm -rf /opt/waterfox
    if sudo test -d /opt/waterfox.previous; then
        sudo mv /opt/waterfox.previous /opt/waterfox
    fi
fi

The version check should begin with BrowserWorks Waterfox. The successful branch removes the rollback tree only after that check passes; the failure branch restores the previous install.

Install the update-waterfox Helper on Ubuntu

If you want a reusable updater command, place it in /usr/local/bin so you can run it from any directory. This script keeps a cache directory under your home folder, checks the installed Waterfox release from waterfox --version, downloads a fresh archive only when Waterfox has moved forward, and stages the replacement before it touches the active /opt/waterfox tree.

The helper is longer because it is doing several jobs for you in one reusable command: checking the latest release, comparing it with the version already installed, skipping the download when nothing changed, staging the new tree, and keeping a rollback copy until the new binary passes a version check.

sudo tee /usr/local/bin/update-waterfox > /dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/waterfox-updater"
STAGING_DIR="/opt/waterfox-new"
BACKUP_DIR="/opt/waterfox.previous"
mkdir -p "$CACHE_DIR"

if ! sudo test -d /opt/waterfox; then
    echo "Install Waterfox from the tarball method before using this updater." >&2
    exit 1
fi

echo "Checking the latest Waterfox release..."
RELEASE_JSON=$(curl -fsSL https://api.github.com/repos/BrowserWorks/Waterfox/releases/latest)
LATEST_VERSION=$(printf '%s\n' "$RELEASE_JSON" | grep -m1 tag_name | cut -d '"' -f4)

if [[ -z "$LATEST_VERSION" ]]; then
    echo "Could not determine the latest Waterfox release." >&2
    exit 1
fi

if command -v waterfox >/dev/null 2>&1; then
    CURRENT_VERSION=$(waterfox --version 2>/dev/null | awk '{print $NF}' || true)
    if [[ -z "$CURRENT_VERSION" ]]; then
        CURRENT_VERSION="unknown"
    fi
else
    CURRENT_VERSION="not installed"
fi

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

DOWNLOAD_URL="https://cdn.waterfox.com/waterfox/releases/${LATEST_VERSION}/Linux_x86_64/waterfox-${LATEST_VERSION}.tar.bz2"
ARCHIVE_PATH="${CACHE_DIR}/waterfox-${LATEST_VERSION}.tar.bz2"

echo "Downloading $DOWNLOAD_URL"
curl -fLo "$ARCHIVE_PATH" "$DOWNLOAD_URL"

echo "Staging Waterfox $LATEST_VERSION"
sudo rm -rf "$STAGING_DIR"
sudo mkdir -p "$STAGING_DIR"
sudo tar -xjf "$ARCHIVE_PATH" -C "$STAGING_DIR" --strip-components=1
sudo test -x "$STAGING_DIR/waterfox"

echo "Replacing /opt/waterfox"
sudo rm -rf "$BACKUP_DIR"
if sudo test -d /opt/waterfox; then
    sudo mv /opt/waterfox "$BACKUP_DIR"
fi
sudo mv "$STAGING_DIR" /opt/waterfox
sudo ln -sf /opt/waterfox/waterfox /usr/local/bin/waterfox

if waterfox --version >/dev/null 2>&1; then
    sudo rm -rf "$BACKUP_DIR"
    echo "Updated Waterfox to $LATEST_VERSION"
else
    echo "Version check failed; rolling back." >&2
    sudo rm -rf /opt/waterfox
    if sudo test -d "$BACKUP_DIR"; then
        sudo mv "$BACKUP_DIR" /opt/waterfox
    fi
    exit 1
fi
EOF

Make the helper executable after you save it.

sudo chmod +x /usr/local/bin/update-waterfox

Run update-waterfox when you want to check for a new release. Do not hide a tarball updater inside a blind cron job unless you are also watching upstream release changes and cleanup behavior.

Confirm that the helper is on your PATH.

command -v update-waterfox

Expected output:

/usr/local/bin/update-waterfox

Remove Waterfox on Ubuntu

Use the removal path that matches the method you installed. Flatpak cleanup and tarball cleanup are separate jobs.

Remove the Waterfox Flatpak on Ubuntu

Remove the Waterfox app itself first. This removes the system-scope app deployment; profile data and shared runtimes are checked in separate steps.

sudo flatpak remove net.waterfox.waterfox -y

Check that Waterfox is no longer listed as an installed Flatpak app.

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

Expected output:

NOT_INSTALLED

If you launched the Flatpak and want to remove leftover app data too, check whether the app created a directory in your home folder before you delete anything.

find "$HOME/.var/app" -maxdepth 1 -type d -name 'net.waterfox.waterfox' 2>/dev/null

If that command prints a path, remove it only after you have backed up anything you want to keep.

The next command permanently removes Waterfox Flatpak profile data, including bookmarks, history, saved passwords, and extensions for that Flatpak app.

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

If you also want to remove unused Flatpak runtimes, review the interactive prompt before confirming because the cleanup can affect other Flatpak apps.

sudo flatpak uninstall --unused

Remove the Waterfox Tarball Install on Ubuntu

Remove the extracted browser tree, the system launcher, the desktop file, and the optional updater helper.

The next commands remove the system-wide Waterfox tarball install and the launchers created in this guide. They do not remove profile data in your home directory.

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

If you used the updater helper, remove its downloaded archive cache too.

rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/waterfox-updater"

Verify that the command is gone from your shell path.

hash -r
command -v waterfox || echo "NOT_FOUND"

Expected output:

NOT_FOUND

Waterfox does not always create user profile directories until you have launched it, so check your home directory before deleting any browser data.

The next commands permanently remove Waterfox profile data, including bookmarks, history, saved passwords, and extensions. Back up any path you want to keep before you delete it.

find "$HOME" -maxdepth 2 \( -path "$HOME/.waterfox" -o -path "$HOME/.cache/waterfox" \) -print 2>/dev/null

If that command prints one or both paths, remove the directories you no longer need.

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

Troubleshoot Waterfox on Ubuntu

Most Waterfox problems on Ubuntu come down to command-line assumptions, Flatpak permissions, or desktop integration after a manual tarball install. Start with the smallest check that matches what you actually changed.

Check Waterfox Command-Line Options on Ubuntu

Waterfox accepts Firefox-style launch flags, but unsupported flags vary by build. Current Waterfox help lists kiosk, profile-manager, and window-opening options; it does not list older app-mode or site-specific-browser flags such as --app or --ssb, so verify before you script those forms.

waterfox --help 2>/dev/null | grep -E -- '--kiosk|--ProfileManager|--new-window|--private-window'

Relevant output includes:

--ProfileManager   Start with ProfileManager.
--new-window <url> Open <url> in a new window.
--private-window <url> Open <url> in a new private window.
--kiosk            Start the browser in kiosk mode.
--kiosk-monitor <num> Place kiosk browser window on given monitor.

For a Flatpak install, run the same help check through Flatpak.

flatpak run net.waterfox.waterfox --help 2>/dev/null | grep -E -- '--kiosk|--ProfileManager|--new-window|--private-window'

Fix Waterfox Flatpak File-Access Limits on Ubuntu

Waterfox on Flathub already has access to the usual desktop folders, but you can inspect the current sandbox rules before you add broader overrides.

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

Relevant output includes:

[Context]
shared=network;ipc;
sockets=x11;wayland;pulseaudio;fallback-x11;cups;
devices=all;
filesystems=xdg-music;xdg-pictures;xdg-videos;xdg-run/speech-dispatcher:ro;~/snap:ro;xdg-download;xdg-documents;~/.mozilla:ro;xdg-desktop;xdg-run/pipewire-0;
persistent=.waterfox;

If you still need one extra path, grant only that directory instead of handing Waterfox your whole home folder.

flatpak override --user --filesystem=~/Documents net.waterfox.waterfox

Fix Missing Waterfox Icons on Ubuntu

If the tarball build launches from the terminal but not from the applications menu, check the desktop entry and the absolute icon path it points to first. This workflow does not install a themed icon under /usr/share/icons, so the important check is whether the desktop file still references the live file under /opt/waterfox.

test -f /opt/waterfox/browser/chrome/icons/default/default128.png && echo "Waterfox icon found"
grep -E '^(Exec|Icon)=' /usr/share/applications/waterfox.desktop
sudo update-desktop-database

Relevant output includes:

Waterfox icon found
Exec=/opt/waterfox/waterfox %u
Icon=/opt/waterfox/browser/chrome/icons/default/default128.png

Conclusion

Waterfox is ready on Ubuntu with either a Flathub-managed install or the official tarball under /opt. If you want to compare other privacy-minded browser workflows next, install LibreWolf on Ubuntu or install Tor Browser on Ubuntu for a different balance of package management, privacy defaults, and browsing isolation.