What it is
Waterfox is an open-source web browser built on Mozilla Firefox, with source code maintained in this repository. The project describes itself as a customisable browser based on the Mozilla Firefox codebase, and the tree contains both the upstream Mozilla platform code and the Waterfox-specific product layer that sits on top of it. It lives in the JavaScript and Gecko browser ecosystem, sharing the rendering engine, build system and testing tooling that Mozilla maintains for Firefox. The browser is distributed to end users through the project's own website, while the source distribution here targets people who want to build, inspect, patch or repackage it themselves.
The concrete problem it addresses is the gap between a stock Firefox build and a browser that a maintainer can shape to their own preferences. Firefox ships with a fixed set of product decisions, packaging conventions and default features. Waterfox keeps the Gecko platform intact but replaces the Firefox branding, product configuration, feature set, packaging and release files with its own. Contributors and downstream packagers therefore get a full browser source tree in which the parts that define the product — not just the engine — are editable in one place, rather than requiring patches against an unchanged upstream release.
Key capabilities
- Ships complete browser source: Mozilla platform code together with Waterfox product code, branding, features, packaging and release files.
- Builds through the Mozilla build system, so the standard
./mach entry points work unchanged.
- Provides
./mach bootstrap, ./mach build, ./mach package and ./mach test --auto for setup, compilation, packaging and automated testing.
- Runs on the Gecko engine, the same engine underlying Mozilla Firefox.
- Supports deep customisation of the browser product layer rather than only surface settings.
- Reuses Firefox Source Docs for the shared build system, testing tools and platform code.
- Carries Waterfox-specific branding and release configuration alongside the inherited platform tree.
Who uses it and how
- End users who want a Firefox-derived browser with Waterfox's own product decisions install packaged builds from the project's site.
- Distributors and packagers build from this tree to produce branded Waterfox release artefacts.
- Developers patch the product layer — branding, features, packaging — while leaving Gecko platform code largely untouched.
- Contributors follow Firefox Source Docs to work on shared Mozilla tooling and platform code inside this repository.
- Testers run
./mach test --auto against local builds before release.
Getting started
Building follows the Mozilla build system: run ./mach bootstrap, then ./mach build, then ./mach package, with ./mach test --auto