# helium-macos is the packaging layer for the Helium browser on macOS

> The helium-macos repository does not contain the browser, it contains the machinery that turns a Chromium source tree into a signed macOS application. It is built on ungoogled-chromium-macos, heavily modified for Helium, and the release cadence of the packages it produces is a few days, with CI runners sponsored by Depot.

**imputnet/helium-macos** — Helium Browser for macOS

- Repository: https://github.com/imputnet/helium-macos
- Stars: 1,164 · Forks: 149
- Language: C++
- License: GPL-3.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/imputnet-helium-macos

## This repository is the packaging, not the browser

The README opens with a one line statement that sets the scope precisely. This repository contains macOS packaging and development tooling for the Helium Browser, and the browser itself lives at imputnet/helium.

That division is the thing to understand before reading anything else. Chromium is built from a source tree that is enormous and that has to be configured, patched, compiled, packaged, signed and notarised before it can be shipped as a Mac application. None of the code that does that is interesting to most contributors, and all of it is specific to a platform, so it lives in a platform repository. The Helium repository holds the browser's own changes, and this one holds the macOS build system.

The repository layout reflects that division. There are the scripts that drive the work, `build.sh`, `dev.sh`, `env.sh` and `sign_and_package_app.sh`, a `devutils/` directory for developer tooling, a `patches/` directory for the changes applied to the Chromium tree, a `resources/` directory, and a `helium-chromium/` directory that holds the Chromium checkout itself, present as a git submodule. There are three download manifests, `downloads.ini`, `downloads.x64.ini` and `downloads.arm64.ini`, which is the usual way to record the artefacts that differ between Intel and Apple Silicon builds, and a `revision.txt` that pins the Chromium revision being built.

The `flags.macos.gn` file is the build configuration in the GN style that Chromium uses, so the build is a normal Chromium build with Helium and macOS specific settings layered on.

The audience is narrow and technical. It is a developer working on Helium who needs to build and run the browser on macOS, and it is anyone who wants to see how a Chromium fork becomes a shippable Mac app.

## ungoogled-chromium is the base, and it has been changed a lot

The credits section names the foundation of the whole approach. This repository is based on ungoogled-chromium-macos, but heavily modified for Helium, and the README thanks the people behind ungoogled-chromium for making working with Chromium infinitely easier.

That is the right way to build a Chromium fork and the reason the project exists in this shape rather than as a set of patches against Google's own tree. The ungoogled-chromium project solved the hard part of the macOS build, the configuration, the binary patching, the packaging and the signing, and a fork that starts from that work inherits all of it.

The word heavily is doing some work in that sentence, and it is worth being clear about what it implies. A build system for Chromium has thousands of files and a patch set can be large, so the distance between this repository and a stock ungoogled-chromium-macos checkout is not something you can read in an afternoon. A contributor who wants to change how the Mac application is built needs to read the patches directory and understand which of them are Helium's own.

The development platform is macOS, and the README says so directly. macOS is the primary development platform for the project and is therefore the recommended environment for developing new Helium features. That is a strong statement about where the work is centred.

The build documentation is in `docs/building.md`, and the contributing guidelines are not in this repository. The README says that before contributing you should read the guidelines in the main repository's CONTRIBUTING.md, so the two repositories are meant to be read together rather than separately.

## Two licences live in the same tree

The licence section is more careful than most, and it is worth reading in full because it explains a structure that would otherwise look inconsistent.

All code, patches, modified portions of imported code or patches, and any other content that is unique to Helium and not imported from other repositories is licensed under GPL-3.0. That covers the `patches/` directory, the scripts, the development tooling and the build configuration, because those are Helium's own work.

Any content imported from other projects retains its original licence. The example given is that any original unmodified code imported from ungoogled-chromium remains licensed under their BSD 3-Clause licence, and the repository carries that text separately in `LICENSE.ungoogled_chromium` alongside the main `LICENSE`.

So the tree holds two licences at once, and the rule for telling them apart is about provenance rather than about files. If a piece of content came in from another project unmodified, its original terms apply. If it is Helium's own or has been modified, it is GPL-3.0.

The practical consequences are the usual ones for a copyleft project. Anyone who distributes a build of the browser has obligations under GPL-3.0 for the Helium-specific parts, and the BSD-licensed imports stay BSD. The BSD material is permissive, so it can be used in a proprietary work, while the GPL-3.0 material cannot be linked into proprietary software without the source being made available.

This is worth understanding before you take anything from this repository into another project, because the two licences have different consequences and a file-by-file audit is the only way to know which applies to what.

## Depot's runners are why a macOS build lands in hours

The credits section explains the release cadence, and it is the most interesting operational fact in the repository.

Depot sponsors the runners that handle the macOS builds of Helium, and the README says their high performance infrastructure lets the team compile, package and release new builds within hours, not days.

The three most recent releases make that concrete. Version 0.19.3.1 was published on 2026-10-15, 0.19.2.1 on 2026-10-09 and 0.19.1.2 on 2026-10-08, and the last push to the repository followed a few days after the newest tag.

Building Chromium from source is famously slow, and on macOS it means compiling a very large C++ codebase for two architectures, since the download manifests exist separately for x64 and arm64. A machine that can do that quickly, and does it in CI on every change, is the difference between a project that ships a Mac build the same day a change lands and one that ships monthly.

The version numbering also tells you something about the relationship to the browser itself. The three-part version with a trailing fourth component, 0.19.3.1, reads as a packaging revision rather than a browser release, which fits the division of labour between the two repositories. A Helium browser version and a helium-macos packaging version are different things, and the numbers here belong to the second.

## The scripts are the interface to the build

There is no package manager entry for this project, and there is not meant to be. What you get is a set of shell scripts at the top of the repository, and the build documentation tells you how to use them.

The four scripts cover the four things you would want to do.

```text
build.sh
dev.sh
env.sh
sign_and_package_app.sh
```

`build.sh` is the production path, producing the application. `dev.sh` is the development path. `env.sh` sets up the environment, which for a Chromium build means the toolchain, the SDK and the variables that tell the build system where everything is. `sign_and_package_app.sh` handles the last step, the code signing and the packaging of the `.app`, which is the part that turns a build output into something a Mac user can install without Gatekeeper complaining.

That last script is the one that explains the sponsor relationship. macOS application signing and notarisation require an Apple developer identity and a network round trip to Apple's notary service, and doing that by hand for every build is a chore. Doing it in CI on sponsored runners is a chore nobody has to do.

The `resources/` directory holds the things that end up inside the application bundle, and `devutils/` holds the development helpers that are not part of the build itself. The `.vscode/` directory at the root and the `.gitattributes` file suggest the project is meant to be worked on in a configured editor, and the `patches/` directory is where the actual changes to the Chromium tree live, which is the file to read when you want to know what Helium changed about the browser on macOS.

The `revision.txt` file is what pins the Chromium revision, and it is the file to look at when you want to know which upstream Chromium this build corresponds to.

## Where to send a change, and what not to expect here

The limitations are about scope rather than quality, and they are easy to get wrong if you approach the repository as if it were the browser.

The first is that behaviour changes do not belong here. If you want to change what the browser does, that is the main Helium repository, and the README says so by pointing contributors at its CONTRIBUTING.md before they contribute here. This repository is the platform layer, so a change that lands here affects every macOS build of the browser, which is a much heavier thing to review and a much heavier thing to get wrong.

The second is that macOS is the focus. The project states that macOS is the primary development platform and the recommended environment for developing new Helium features, which means the workflows, the scripts and the runner configuration are tuned for that platform. Someone working on Helium from Linux or Windows is working in the sub-optimal path, and the other platform repositories have to cover the rest.

The third is that the size of the Chromium tree makes this repository hard to read. A patch set applied to a browser source tree is thousands of lines, and the value of the repository is not in reading it end to end but in knowing which patch to touch. The documentation in `docs/building.md` is the entry point for that.

The alternative to working in this repository is, for a macOS user who just wants the browser, the packaged release that comes out of this pipeline. For a developer who wants to change the browser, the main repository. For a developer who wants to change how the macOS build works, this one. The tooling exists so that the second case does not require re-solving the first, and the division is deliberate.

## Conclusion

helium-macos suits a developer who wants to work on the Helium browser on macOS, or who wants to understand exactly how a Chromium build is turned into a signed Mac application and which patches are applied. It is the wrong repository to change browser behaviour in, since the browser itself lives in the main Helium repository, and the wrong place to look for the project contribution guidelines, which also live upstream. Check first the build documentation in `docs/building.md`, and read the two licence files before you copy anything from this tree into your own project.

## FAQ

### What does the helium-macos repository contain?

It contains the macOS packaging and development tooling for the Helium browser: the build and development scripts, the patches applied to the Chromium tree, the development utilities and the build configuration. The browser itself lives in the separate imputnet/helium repository.

### What is helium-macos based on?

It is based on ungoogled-chromium-macos, but heavily modified for Helium. The README credits the ungoogled-chromium project with making working with Chromium much easier, and imported content that is unmodified keeps its original BSD 3-Clause licence.

### Which licence applies to the code in helium-macos?

Code, patches and any content unique to Helium is licensed under GPL-3.0, while content imported unmodified from other projects keeps its original licence, such as the BSD 3-Clause licence for ungoogled-chromium code. The repository carries both texts, in `LICENSE` and `LICENSE.ungoogled_chromium`.

### Where do I contribute a change to Helium?

The README asks contributors to read the guidelines in the main repository's CONTRIBUTING.md at imputnet/helium before contributing here. macOS is the primary development platform and the recommended environment for developing new Helium features, and the build instructions are in `docs/building.md` in this repository.

## Sources

- [imputnet/helium-macos on GitHub](https://github.com/imputnet/helium-macos)
- [Issues](https://github.com/imputnet/helium-macos/issues)
- [License: GPL-3.0](https://github.com/imputnet/helium-macos/blob/main/LICENSE)
- [README](https://github.com/imputnet/helium-macos/blob/main/README.md)
- [Releases](https://github.com/imputnet/helium-macos/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/imputnet-helium-macos