Helium Browser for Windows: source build and packaging

What helium-windows packages for Windows

helium-windows is the Windows packaging repository for Helium, not the browser's complete C++ application source in the usual sense. Its purpose is to obtain Chromium, apply Helium's changes, package the resulting browser and create Windows deliverables. The repository is described as "Windows packaging for Helium" and contains build.py, package.py, downloads.ini, downloads.x64.ini, flags.windows.gn, patches, resources and installer-related files. Based on that layout, the central concern is the Windows build and distribution pipeline rather than a standalone graphical application.

The intended users are contributors and Windows packagers who need to compile Helium from source. The README does not provide a short installation path for ordinary browser users, and it does not document a binary download location in the supplied repository text. It does document producing a ZIP archive and an installer under build. The practical adoption question is therefore whether an organization needs control over how its Windows Helium build is assembled. A user who only wants an already built browser cannot confirm a supported download or install procedure from this README alone.

The repository also modifies the workflow inherited from ungoogled-chromium-windows. The README gives credit to that project and says this repository is heavily modified for Helium. That lineage matters for maintenance because the build expects imported scripts and source retrieval steps associated with ungoogled-chromium. It does not mean helium-windows is merely an unchanged copy. Its own Helium-specific patches, pruning configuration and packaging files are part of the package.

The build.py to package.py packaging path

The documented flow has two top-level Python programs. First, build.py downloads the required Chromium source, applies or prepares Helium modifications, and compiles the browser. Second, package.py turns the built files into distributable Windows artifacts. The resulting outputs are described as a ZIP archive and an installer created under build. This separation gives packagers distinct stages for source preparation and packaging, but it also means a failed package step occurs after the expensive browser build has already taken place.

The repository includes separate downloads.ini and downloads.x64.ini files, plus flags.windows.gn for Chromium build settings. The presence of helium-chromium, patches and devutils shows that the Windows package is assembled from imported Chromium material and maintained modifications rather than from a simple standalone compilation. The README's patch workflow uses helium-chromium\utils\clone.py to populate build\src, update_lists.py with a domain-regex list, and quilt through update_patches.sh. These files provide a more concrete view of the data flow than the name "packaging repository" alone: source is fetched into build\src, lists and patches are maintained, and the packaging scripts process that prepared tree.

The README does not specify the exact command-line switches for build.py or package.py. It only gives the two script invocations in the main build recipe. It also does not explain whether an incremental rebuild is safe after package.py fails. For that case, the documented recovery text focuses on build.py, including preservation or removal of build\download_cache depending on where the failure occurred.

Prerequisites that determine whether the Windows build is practical

The build requires more than a C++ compiler. The README directs contributors to the official Chromium Windows build instructions for Visual Studio, then adds 7-Zip, Windows Developer Mode, Python 3.11 or above, Git, requests and Pillow. Windows Developer Mode is needed because the packaging process creates symbolic links. Git must be installed with the option for using it from the command line and other software, since Git fetches required ungoogled-chromium scripts.

A particularly concrete Windows constraint is the MAX_PATH limit. The Python build scripts need paths longer than the default 260-character restriction, and the README says to enable long paths through the Python installer or Microsoft's documented Windows mechanism. It also discusses disabling App execution aliases when using a non-Microsoft-Store Python installation, because python.exe or python3.exe may otherwise resolve to the wrong command. These details make the source build unsuitable for a casual one-command setup.

Visual Studio must be present before running the build in a Developer Command Prompt for VS as administrator. If Visual Studio or the Windows SDK is installed outside standard locations, the README names three environment variables that can be adjusted: vs2019_install, WINDOWSSDKDIR and GYP_MSVS_VERSION. The repository text presents these as values that may need replacing according to the installed versions, so they are configuration examples rather than universal settings.

The prerequisite set also contains a licensing boundary. Helium-specific code, patches and other unique content are under GPL-3.0, while imported content retains its source project's license. For example, unmodified code imported from ungoogled-chromium remains under BSD 3-Clause. This is not legal advice, but distribution and modification decisions need to account for both files.

Cloning and building the first Windows package

Start from a Developer Command Prompt for VS running as administrator, after installing the Chromium build dependencies. The following is the documented clone and checkout recipe. Replace TAG_OR_BRANCH_HERE with a tag or branch name before running it.

git clone --recurse-submodules https://github.com/imputnet/helium-windows.git
cd helium-windows
# Replace TAG_OR_BRANCH_HERE with a tag or branch name
git checkout --recurse-submodules TAG_OR_BRANCH_HERE

The recursive flags matter because the build expects submodules, and the repository must be checked out at the intended tag or branch before compilation. The README then gives these two build commands:

python3 build.py
python3 package.py

Read them as sequential stages. build.py performs the source download and Chromium build work. package.py creates the distribution artifacts afterward. The README says to expect a ZIP archive and an installer under build, but it does not provide a documented launch command or post-install configuration example. Consequently, the first confirmed use available from this repository text is building and packaging the application, not operating Helium through a documented CLI.

The Python dependencies are installed with this command:

python -m pip install requests Pillow

The Scripts directory for Python must be on PATH according to the README. The page does not give a version pin for either dependency, so the repository documentation supports installing the named packages but does not establish a reproducible dependency lock.

Recovering from build.py failures without losing the download cache

The recovery guidance is specific about which part of build should be retained. If build.py fails while downloading Chromium source code, remove build\download_cache and run the build instructions again. If it fails at any other point during build.py, remove everything under build except build\download_cache. The README explains that this clears generated build code and files while retaining the downloaded source cache where appropriate.

That distinction can save a long download, but it is also a warning about the pipeline's state. A build directory is not just an output folder. It contains both generated material and a cache whose value depends on the failure stage. Treating every failed build as a disposable directory would discard the cache. Treating every failed build as resumable could leave stale or incomplete generated state when the failure was not during download.

The README gives Remove-Item PATH -Recurse -Force as an efficient deletion method and warns that deleted files are permanently lost. It does not document rollback of a packaged installer, partial ZIP recovery or a supported retry policy for package.py. For a production build pipeline, that missing rollback information is a meaningful boundary. The documented recovery path covers build.py categories, but it does not establish how to recover an artifact that was already installed or distributed.

Patch maintenance depends on a second shell and quilt

Updating Helium's patch set is separate from producing a release build. The README asks contributors to use a Developer Command Prompt for VS and an MSYS2 MSYS shell. In MSYS2, the initial setup installs tools with pacman -S quilt python3 vim tar, then creates a vi symlink because the default MSYS2 environment may not provide one. This adds another environment to maintain alongside Visual Studio and Python.

The source preparation command is:

python3 helium-chromium\utils\clone.py -o build\src

The README then updates a pruning list using the following command:

python3 helium-chromium\devutils\update_lists.py -t build\src --domain-regex helium-chromium\domain_regex.list

In the MSYS2 shell, devutils\update_patches.sh merge prepares the patch environment, set_quilt_vars.sh sets the quilt variables, and update_patches.sh unmerge removes the Helium-introduced patches after quilt refreshes them. check_patch_files.sh then checks the series file for consistency. The README points to ungoogled-chromium's patch documentation for the detailed quilt procedure.

This workflow is useful when the browser's source modifications need deliberate review. It is not a lightweight extension mechanism for adding an isolated preference or plugin. The repository's own commands operate across a cloned Chromium tree and a patch series, so contributors should expect source-level maintenance rather than configuration-only changes.

Release availability, maintenance and upgrade obligations

The repository is not archived. Its last push was on 2026-10-16, and the listed releases include 0.19.3.1 on 2026-10-15, 0.19.2.1 on 2026-10-08 and 0.18.3.1 on 2026-10-03. These dates show recent release activity, but the README does not define a support policy, upgrade compatibility promise or changelog process beyond the listed releases. A packager should treat the release tags as concrete build targets and verify their relationship to the current source tree.

An upgrade can involve more than downloading a newer Windows executable. The build depends on Chromium source, submodules, patches, Python scripts, Visual Studio components and imported ungoogled-chromium material. A new tag may therefore change build prerequisites or patch expectations. The repository does not provide a documented migration guide for existing packagers, so compatibility with an existing patch series or downstream installer configuration cannot be assumed from the release number alone.

The maintenance burden is therefore concentrated in source synchronization and patch maintenance. Contributors need the MSYS2 tooling for quilt operations, the Windows build environment for compilation and careful review of changes under the mixed GPL-3.0 and retained upstream licenses. The repository layout supports that work, but it does not remove the cost of tracking imported Chromium changes.

Editorial conclusion

Adopt helium-windows if you need to build or maintain Helium's Windows package and have the documented Chromium toolchain available. Do not treat it as a turnkey browser installer or choose it for an unsupported Windows configuration. Verify Visual Studio setup, the MAX_PATH setting, Python packaging commands and the licensing boundary before starting, because the documented build starts with python3 build.py and python3 package.py.

Frequently asked questions

Official sources

1. imputnet/helium-windows on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases