Skip to main content

​
Prerequisites

Before starting, ensure you meet all build requirements.
Quick Checklist:
  • 32GB+ RAM (16GB minimum)
  • 100GB+ free disk space
  • Python 3.8 or newer
  • Git 2.30 or newer
  • Platform-specific build tools installed
  • 4-8 hours available for first build

​
Build Process Overview

Building Helium involves several stages:

​
Step 1: Clone Helium Repository

First, clone the Helium source repository: 
# Clone the repository
git clone https://github.com/imputnet/helium-source.git
cd helium-source
This repository contains the patches, build configuration, and utilities needed to build Helium. The actual Chromium source will be downloaded in the next step.

​
Step 2: Clone Chromium Source

Use the provided clone.py utility to download Chromium source and all dependencies: 
# Clone Chromium and dependencies (takes 30-60 minutes)
python3 utils/clone.py --output chromium

​
What This Does

The clone script performs several operations:
1

Clone Chromium Source

Downloads Chromium source at the specific version tag (145.0.7632.116) with depth=2
2

Set Up depot_tools

Clones and configures Chromium’s build tools (depot_tools)
3

Clone gsutil

Sets up Google Cloud Storage utilities for downloading dependencies
4

Clone GN

Downloads the GN build file generator
5

Run gclient sync

Downloads all third-party dependencies and libraries
6

Download PGO Profiles

Fetches Profile-Guided Optimization profiles for better performance
7

Generate Version Headers

Creates version headers (LASTCHANGE, gpu_lists_version.h, etc.)

​
Clone Options

​
--output
string
default:"chromium"
Output directory for the cloned sources
​
--pgo
string
default:"linux"
PGO profile to download: linux, mac, mac-arm, win32, win64, win-arm64
​
--sysroot
string
Download a Linux sysroot: amd64, arm64, armhf, i386, mips64el, mipsel
​
--custom-config
string
Path to custom gclient config file (advanced)
The clone process downloads 30+ GB of data. Ensure you have:
  • A stable internet connection
  • Sufficient bandwidth quota
  • Patience (30-60 minutes on a fast connection)

​
Step 3: Download Additional Components

Download Helium-specific components: 
# Create download cache directory
mkdir -p download_cache

# Download components
python3 utils/downloads.py retrieve \
  -i deps.ini \
  -c download_cache

# Unpack into source tree
python3 utils/downloads.py unpack \
  -i deps.ini \
  -c download_cache \
  chromium

​
Downloaded Components

This downloads and verifies:
Version: 1.69.0-2Pre-configured uBlock Origin extension that will be built as a component extension.
  • Custom filter lists
  • Helium Services integration
  • Optimized assets
Version: 202601021937The welcome page shown at helium://setup for new users.
  • Introduction to Helium features
  • Initial setup workflow
  • Search engine selection
Prepopulated search engine configurations including icons and templates.
  • DuckDuckGo, Brave Search, Startpage
  • Google, Bing (with privacy warnings)
  • Regional search engines

​
Hash Verification

All downloads are verified using SHA-256 checksums: 
# Downloads are automatically verified
# If verification fails, you'll see:
ERROR: File checksum does not match: download_cache/ublock-origin-1.69.0-2.zip
If a download is interrupted, re-run the command. If curl is available, downloads will automatically resume from where they stopped.

​
Step 4: Apply Patches

Apply all Helium patches to the Chromium source: 
# Apply patches (takes 5-10 minutes)
python3 utils/patches.py apply chromium patches

​
Patch Application Process

The patches are applied in order from patches/series:
  1. Upstream fixes (48 patches) - Vertical tabs and other backported features
  2. Inox patches (4 patches) - Privacy enhancements
  3. Iridium patches (2 patches) - Disable tracking
  4. ungoogled-chromium (46 patches) - Core privacy and de-googling
  5. Bromite patches (3 patches) - Fingerprinting protection
  6. Brave patches (4 patches) - Import functionality
  7. Helium patches (171 patches) - Helium-specific features and UI

​
Monitoring Progress

# You'll see output like:
* Applying upstream-fixes/missing-dependencies.patch (1/276)
* Applying upstream-fixes/vertical/r1568708-fix-crash-during-collapsed-tabgroup-drag.patch (2/276)
...
* Applying helium/ui/layout/vertical.patch (276/276)

​
Troubleshooting Patch Failures

If a patch fails to apply:
# Check which files are causing conflicts
python3 utils/patches.py apply chromium patches --fuzz 0

# For dry-run to see what would fail:
from utils.patches import dry_run_check, find_and_check_patch
from pathlib import Path

for patch in Path('patches').glob('**/*.patch'):
    code, stdout, stderr = dry_run_check(patch, Path('chromium'))
    if code != 0:
        print(f"Failed: {patch}")
Contact the Helium team if patches consistently fail to apply.

​
Step 5: Configure the Build

Generate the build configuration using GN: 
# Navigate to source directory
cd chromium

# Generate release build configuration
gn gen out/Default --args="
  import(\"//helium_args.gni\")
  is_debug=false
  is_official_build=true
  symbol_level=0
  "

​
Build Configuration

Helium uses custom build flags defined in flags.gn: 
# Core build settings
build_with_tflite_lib=false           # Disable TensorFlow Lite
chrome_pgo_phase=0                     # Use downloaded PGO profiles
clang_use_chrome_plugins=false         # Don't use Chromium plugins
disable_fieldtrial_testing_config=true # Disable A/B testing

# Feature flags
enable_hangout_services_extension=false  # No Hangouts
enable_mdns=false                        # No mDNS
enable_remoting=false                    # No Chrome Remote Desktop
enable_reporting=false                   # No crash reporting
enable_service_discovery=false           # No service discovery
enable_widevine=true                     # Keep Widevine DRM

# Privacy settings
safe_browsing_mode=0                   # Disable Safe Browsing

# Build optimizations
exclude_unwind_tables=true             # Reduce binary size
treat_warnings_as_errors=false         # Don't fail on warnings

# API keys (empty for privacy)
google_api_key=""
google_default_client_id=""
google_default_client_secret=""
use_official_google_api_keys=false

​
Verifying Configuration

# List all build arguments
gn args out/Default --list

# Show specific argument value
gn args out/Default --list=enable_widevine

# Show all non-default values
gn args out/Default --short

​
Step 6: Build Helium

Compile the browser using Ninja: 
# Build everything (2-8 hours first time)
cd chromium
ninja -C out/Default chrome

​
Build Time Estimates

First Build

2-8 hours
  • High-end workstation (16+ cores, 64GB RAM): 2-3 hours
  • Mid-range (8 cores, 32GB RAM): 4-6 hours
  • Lower-end (4 cores, 16GB RAM): 6-8 hours

Incremental Build

5-30 minutesRebuilds only changed files and their dependencies. Time varies based on scope of changes.

​
Monitoring Build Progress

# Build with progress indication
ninja -C out/Default chrome -v

# In another terminal, monitor compilation
watch -n 5 "ps aux | grep 'clang\|link' | wc -l"

​
Build Output

The compiled browser will be located at: 
chromium/out/Default/chrome
The main executable is chrome. Run with:
./out/Default/chrome

​
Common Build Issues

Symptom: Build crashes with “Killed” or memory errors during linkingSolutions:
# Reduce parallel jobs
ninja -C out/Default -j2 chrome

# Or use gold linker (Linux only)
gn gen out/Default --args="...existing args... use_gold=true"

# Or disable LTO (Link Time Optimization)
gn gen out/Default --args="...existing args... use_thin_lto=false"
Symptom: Compilation fails with errors in modified codeSolutions:
# Ensure all patches were applied
python3 utils/patches.py apply chromium patches

# Check for conflicting local changes
cd chromium
git status
git diff

# Clean and rebuild
rm -rf out/Default
gn gen out/Default --args="..."
ninja -C out/Default chrome
Symptom: Build takes much longer than expectedSolutions:
# Enable ccache
gn gen out/Default --args="...existing args... cc_wrapper=\"ccache\""

# Use all available cores
ninja -C out/Default -j$(nproc) chrome

# Disable debug symbols in release builds
gn gen out/Default --args="...existing args... symbol_level=0"

# Use faster linker (Linux)
gn gen out/Default --args="...existing args... use_lld=true"

​
Step 7: Run and Test

Run your newly built Helium browser: 
# Linux
./out/Default/chrome

# macOS  
open out/Default/Helium.app

# Windows
.\out\Default\chrome.exe

​
Testing Checklist

1

Launch Browser

Verify the browser launches without crashes
2

Check Branding

Confirm “Helium” branding appears correctly in UI and about page
3

Test uBlock Origin

Open helium://extensions and verify uBlock Origin is installed and active
4

Visit Test Sites

Test browsing functionality on various websites
5

Check Privacy Features

Use privacy testing sites to verify fingerprinting protection

​
Next Steps

Understanding Patches

Learn how to work with and modify Helium patches

Development Workflow

Return to the development overview

​
Additional Resources

Chromium Build Docs

Official Chromium build documentation

ungoogled-chromium

Learn more about the base project

Build docs developers (and LLMs) love

Get started for freeTalk to us