Skip to main content

​
Introduction

Helium is a privacy-focused Chromium-based web browser built on top of ungoogled-chromium. This page provides an overview of the project architecture and development workflow.

​
Architecture

Helium’s architecture consists of several key components:

​
Base Layer: Chromium

Helium is built on Chromium version 145.0.7632.116, providing a solid foundation with:
  • Modern web standards support
  • Security updates from the Chromium project
  • Cross-platform compatibility (macOS, Linux, Windows)

​
Privacy Layer: ungoogled-chromium

Built on ungoogled-chromium, Helium inherits:
  • Removal of Google integration and dependencies
  • Disabled automatic connections to Google services
  • No crash reporting or metrics collection
  • Removed binary blobs where possible

​
Helium Enhancements

Helium adds its own features and modifications:

Privacy Features

  • Canvas, audio, and hardware fingerprinting noise
  • Reduced Accept-Language headers
  • Disabled ad topics and privacy sandbox
  • Client hints removal

UI Improvements

  • Custom color scheme and theming
  • Redesigned toolbar and tabs
  • Cleaner new tab page
  • Removed unnecessary UI elements

Integrated Components

  • uBlock Origin as a built-in component
  • Helium Services integration
  • Custom onboarding experience
  • Native bang support

Browser Behavior

  • Parallel downloading enabled
  • Infinite tab freezing for memory savings
  • MRU tab cycling
  • Split view support

​
Patch-Based Development

Helium uses a patch-based development model inherited from ungoogled-chromium:

​
Patch Categories

Patches are organized by source and purpose:
Fixes from Chromium upstream, particularly for vertical tabs and other features backported to the current version.
Core privacy patches that disable Google services, telemetry, and tracking. These form the foundation of Helium’s privacy features.
Core Helium functionality including services integration, branding, search engine configuration, and feature flags.
User interface modifications including layout changes, color schemes, toolbar redesign, and visual improvements.
Settings page modifications to remove unnecessary options and add Helium-specific configurations.

​
Build System

Helium uses the standard Chromium build system with customizations:

​
GN (Generate Ninja)

Build configuration is defined in flags.gn: 
build_with_tflite_lib=false
chrome_pgo_phase=0
clang_use_chrome_plugins=false
disable_fieldtrial_testing_config=true
enable_widevine=true
safe_browsing_mode=0
treat_warnings_as_errors=false

​
Ninja

The actual build is performed by Ninja, a fast parallel build system.

​
Python Utilities

Helium includes custom Python utilities for:
  • clone.py - Cloning Chromium source with dependencies
  • patches.py - Applying GNU Quilt-formatted patches
  • downloads.py - Downloading and verifying additional components

​
Platform Packaging

Helium is packaged separately for each platform:

macOS

Universal binary with auto-updates

Linux

AppImage format for wide compatibility

Windows

Standalone installer

​
Development Workflow

The typical development workflow involves:
1

Clone Source

Use clone.py to download Chromium source and dependencies
2

Download Components

Use downloads.py to retrieve uBlock Origin, onboarding page, and search engine data
3

Apply Patches

Use patches.py to apply all patches in the correct order from patches/series
4

Configure Build

Generate build files with GN using the configuration in flags.gn
5

Build

Compile the browser using Ninja
6

Test & Package

Test the build and create platform-specific packages

Helium Services

Backend services for extension proxying and updates

Helium Onboarding

Welcome page shown at helium://setup

uBlock Origin CRX

Packaging repository for uBlock Origin integration

​
Continuous Integration

Helium uses Cirrus CI for automated testing:
  • Code quality checks - yapf formatting and pylint linting
  • Configuration validation - Verify config files are valid
  • Patch validation - Test that all patches apply cleanly
  • Build verification - Ensure the source tree builds successfully
The CI pipeline runs on containers with 8 CPU cores and 32GB memory to handle Chromium’s large codebase.

Build docs developers (and LLMs) love

Get started for freeTalk to us