Goma for Chromium contributors

This document describes how to install and use Goma. It is intended for early access for external Chromium contributors.

Getting started

This section explains the one-shot procedure to start using the Goma service. You need to do the following once you start using Goma.

System requirements

  • A x86-64 machine with at least 8GB of RAM.
  • Linux
  • You must have python 3.3 or later installed already.
  • You must have depot_tools installed already. Please make sure your PATH environment variable has depot_tools path.

Most development is done on Ubuntu (currently 16.04, Xenial Xerus). It might work on other distros, but they are mostly unsupported.

Please wait for invitation from Google

You can use the Goma service upon invitation from Google

We will gradually invite active external Chromium contributors to use the Goma service (i.e. using Goma backend server paid for by Google).

For contributors who have tryjob access, please ask a Googler to email accounts@chromium.org on your behalf. Note that this is a best-effort process. We do not guarantee when you will be invited.

The rest of the procedures will work after you are registered as a Goma user.

Login to Goma service

Please use goma_auth in depot_tools to login. To use Goma service, you must agree to our data usage policy.

$ goma_auth login

Note: goma_auth understands https_proxy environment variable.

How to build Chromium with Goma?

This section explains the typical workflow for using Goma.

Start compiler_proxy daemon

$ goma_ctl ensure_start

Note: goma_ctl understands https_proxy environment variable.

Build chromium using Goma

$ cd ${chromium_src}
$ gn gen out/Default --args="use_goma=true"

Or, execute gn args out/Default and add followings:


Then, build chromium using Goma.

$ cd ${chromium_src}
$ autoninja -C out/Default


How to use the latest Goma client?

If there is a new Goma client commit, the prebuilt Goma client in cipd repository will automatically be updated, but your installation won't be updated automatically.

To update your Goma installation, please execute update_depot_tools, when the machine is not using Goma. i.e. building chromium.

$ update_depot_tools

Note: gclient sync will run update_depot_tools automatically.

How to temporarily disable GOMA

If you want to temporarily disable GOMA to run your compilation 100% locally (e.g. because you are offline), you may use the following environment variable:


Do not change use_goma in your gn args, otherwise you would trigger a full rebuild.

Known issues

compiler_proxy takes CPU after builds

compiler_proxy might take unnecessary CPU after build finished.

It's ok to restart compiler_proxy when it happens.

$ goma_ctl restart

or, stop if you don't need to use goma for a while.

$ goma_ctl ensure_stop

Don't forget to start goma before build.

$ goma_ctl ensure_start


goma_ctl ensure_start shows error: failed to connect to backend servers

  1. Please make sure you have logged in with an email address that you have registered.

    The following command shows which user is currently logged in. Please confirm that the email address shown is the same one that you had used to nominate yourself as a Goma user.

    $ goma_auth info

    This also shows your account is registered as a Goma user or not. If not, please file an issue in crbug.com with Infra>Goma component.

  2. Please make sure you do not set GOMA_* environment by yourself.

    The following command should not show anything.

    $ env | grep ^GOMA_

If all of above did not help, please file an issue in crbug.com with Infra>Goma component. Please include the following information:

  • output of cipd installed -root ${depot_tools_dir}/.cipd_bin
  • goma-report.tgz generated by goma_ctl report It contains all logs generated by goma client. TODO: explain what is shared and reason to share?

TODO: create template on crbug.com?