Google Omaha Tutorial

Google Omaha is the technology which implements automatic updates in Chrome. It is open source but difficult to set up. This tutorial gives an overview of how it works, so you can use it for your own applications.

How Chrome's auto-update mechanism works

When you install Chrome, you are actually running a binary built with Omaha. This binary contacts Google's servers and asks "what's the latest version of Chrome?" The server responds with the URL of a .exe file that can be used to install Chrome. Omaha downloads this file and runs it. It also displays a simple GUI with progress information:

The .exe which was downloaded by Omaha installs Chrome into C:\Program Files (x86)\Google\Chrome. It also creates registry keys at HKLM\Software\Wow6432Node\Google\Update\Clients:

If you're wondering about Program Files (x86) and Wow6432Node, that's because Omaha is still a 32-bit application, probably for maximum compatibility with existing systems. (What's also interesting is that even 64-bit Chrome is installed into Program Files (x86) and not Program Files.)

The registry keys in the screenshot are a vital point of communication between Omaha and the applications it manages. Each application that wants to be kept up to date by Omaha needs to have a registry key under Software\​Wow6432Node\​Google\​Update\​Clients. Chrome is registered there under the globally constant id {8A69D345-D564-463c-AFF1-A69D9E530F96}. You can see in the screenshot that its version is 52.0.2743.116. Another interesting id is {430FD4D0-...}. This is the key Omaha uses to update itself! ;-)

Omaha also sets up two tasks in the Windows Task Scheduler:

You sometimes see them as GoogleUpdate.exe in the Task Manager:

When the update tasks run, Omaha looks at the registry keys shown above to see which applications need to be updated, and what versions they are at. It sends this information to the update server. If a new version is available, the server responds with the URL of an .exe file which can be used to update the respective application.

A nice feature of this .exe-based approach is that Omaha and the update server are completely agnostic of the applications they manage. The only thing the two components need are executables which perform the application-specific update/installation steps.

Another important feature of Omaha is that it handles permission issues. For example, Chrome may be installed with an administrator account, but then run under a normal user account without permissions to perform updates. Omaha performs all update and installation tasks with the same privileges as the original installation. This for instance allows a non-privileged user to "check for updates" in a system-wide installation.

Using Omaha in your own projects

Omaha is open source. To use it in your own projects, you need to modify its C++ code, install the necessary tools to compile it, and set up a server. If you want to avoid spending weeks on these tasks, we can do them for you:

The rest of the tutorial assumes that you have an update server and a fork of Omaha that fetches updates from this server.

Build an installer

As explained above, Omaha always receives .exe files in response to install/update requests. For instance, the client says "I would like to install app XYZ" and the server answers "You can do this with https://.../install.exe". Likewise for updates: The client says "I have version 1.0 of XYZ, is there an update?" and the server responds "Yes, there's 1.1. You can use https://.../update.exe to update."

We will now build the most basic installer.exe. We use Go for this task but you may also use other technologies such as NSIS, as long as your installer supports "silent installation".

Please install Go if you don't already have it. Then create a file install.go with the following contents:

package main

import ""

func check(e error) {
   if e != nil {

func main() {
   const company = `Company`
   const product = `Product`
   const productId = `{9B01C5D1-7F78-4A4E-A89B-0415F6466BC7}`
   const version = ``

   regKey := `SOFTWARE\` + company + `\Update\Clients\` + productId
   k, _, err := registry.CreateKey(registry.LOCAL_MACHINE, regKey, registry.WRITE | registry.WOW64_32KEY)
   defer k.Close()
   check(k.SetStringValue("pv", version))
   check(k.SetStringValue("name", product))

You need to set company, product and productId in the snippet to match the values in the code of your fork of the Omaha client. If you obtained Omaha from us, then we sent you the values to use.

Assuming Go is on your PATH, you should be able to build install.go after into the directory containing it:

set GOPATH=%cd%
go get
go build install.go

When you run the generated install.exe, a new registry key should be created at HKLM\​SOFTWARE\​Wow6432Node\​Company\​Update\​Clients\​{GUID}.

You may wonder why we are creating this strange registry key. The reason is that if installer.exe doesn't create this key, then Omaha believes that the installation failed. The registry is thus a crucial point of contact between your app and Omaha.

Upload the installer to the server

Log in to /admin on the update server. Click on Omaha/Applications on the left-hand side. Add an application with ID the same value as the productId above and name the value from product. Do include the curly braces {} in the ID:

Click on Versions on the left. Add a version for your app, in the stable channel, with number the same as version in the install script. Upload install.exe from the previous step as the file. Click "Add another Action" at the bottom. Select install as Event and enter install.exe into Run. Click Save.

Install your app with Omaha!

We can now use Omaha to install our very basic app. Before we do this however, we want to clean up any remainders of a previous installation:

  1. Delete the registry key HKLM\SOFTWARE\Wow6432Node\Company\Update.
  2. Delete the directory C:\Program Files (x86)\Company\ (if it exists).

In both steps, please replace Company by the corresponding value from your fork of Omaha.

Your Omaha binaries should include an analogue to GoogleUpdate.exe, possibly named after your company instead of Google. Execute it on a command line, with the following parameters:

CompanyUpdate.exe /install "bundlename=Product&appguid={9B01C5D1-7F78-4A4E-A89B-0415F6466BC7}&appname=Product&needsadmin=True&lang=en"

(Replace the company, product name and ID by your own values.) If all goes well, you should see a standard installer GUI, eventually notifying you that the installation was successful:

At this point, you may want to check that the registry key at HKLM\​SOFTWARE\​Wow6432Node\​Company\​Update\​Clients\​{GUID} was again created. If not, please see Troubleshooting below.


If the installation with Omaha was unsuccessful, then it may help to turn on logging in Omaha. You can do this by creating the file C:\CompanyUpdate.ini (replace Company as usual) with the following contents:



LogFilePath="C:\Omaha log.txt"



This snippet is from Omaha's documentation. It works if you are running a debug build of Omaha. It produces c:\Omaha log.txt, which you can inspect for any glaring error messages. What may further be enlightening is to search for <request> / <response> in the log and compare this with the protocol specification. And as always, we are also happy to help:

Update your app

Now that your app is "installed", it is time to create an update. Replace the version in install.go by a higher value, eg. Compile install.go as before. Log into the update server's admin interface, and create a new Version for your app there (ensure you use the version number from install.go). Upload the newly generated install.exe. Click Add another Action at the bottom. This time however, select update as event. Enter install.exe into Run. Click Save.

To force an update check, delete the registry key HKLM\​Software\​Wow6432Node\​Company\​Update\​LastChecked. Open the Windows Task Scheduler and run the task CompanyUpdate...UA by right-clicking. You should now see CompanyUpdate.exe in the list of running processes in the Windows Task Manager. Once it has disappeared from the list, the registry key at HKLM\​SOFTWARE\​Wow6432Node\​Company\​Update\​Clients\​{GUID}\pv should have been updated to the new version. This means that your update was successfully applied. Congratulations! You have successfully completed this tutorial. If you have questions or comments, we would love to hear from you. Just get in touch.

Further Considerations

Now that you have completed the tutorial, you will want to apply your knowledge to create a real-world installer for your own app. Here are some tips for issues you will likely encounter.

Tagged Meta Installer

To install our app in the tutorial, we had to execute the complicated command line CompanyUpdate.exe /install .... You obviously don't want your users to have to type this. Omaha addresses this issue via Tagged Meta Installers. These are .exes which wrap CompanyUpdate.exe with hard-coded command line arguments (/install ....) so the user can simply double-click the file. If you obtained Omaha from us, then we also supplied you with such an installer. Otherwise, you need to create it yourself following the instructions in the link just mentioned.

Code signing

Windows executables need to be signed or your users may get ugly warnings:

In particular, Omaha needs to be built with a code signing certificate if you want to make sure such warnings are not shown. When you obtain Omaha from us, we assist you with this (or do it for you). Otherwise, you need to supply the --authenticode_file and --authenticode_password parameters to Omaha's build.

Packaging files with Go

Our Go-based installer in the tutorial only created some registry keys. But a real-life installer will also need to package and extract some files. One way of doing this in Go is via go-bindata. This library allows packaging arbitrary files inside a Go-built binary. Again, if you obtain Omaha from us, we can also provide you with an installer, custom-tailored to your app.

User/machine installations

Throughout this tutorial, we have performed machine installations, meaning that Omaha's binaries were installed in C:\Program Files (x86) and registry keys were created under HKEY_LOCAL_MACHINE. Omaha also supports user installations. These install apps for the current user only, in C:\​Users\​%user%\​AppData\​Local, and create registry keys under HKEY_CURRENT_USER. You will likely want to support both kinds of installation. The following very simplistic Go function can be used in your installer to determine if a user- or machine install is being performed:

func isUserInstall() bool {
   return strings.HasPrefix(os.Args[0], os.Getenv("LOCALAPPDATA"))

Command line arguments

The update server currently only allows uploading one .exe per Version. This .exe needs to be able to both perform a clean install as well as an update from a previous version of an app. To tell the installer whether to install or to update, you can use command-line arguments. When you add the Version in the admin menu, supply two Actions, one for Event install and one for Event update, with different Arguments (eg. -install and -update). You can parse these arguments in your installer to determine which action to perform.

Directory structure

Omaha's update task may run at any time, in particular while an instance of your app is running. When an update needs to be performed, you usually cannot simply overwrite your app's files while it is running. To address this issue, we recommend creating a separate directory for each version of your application:

  • C:\Program Files (x86)\Company\YourApp\
    • launcher.exe <- looks at available versions and launches the latest one.
      • app.exe <- latest version

When performing an update, you can then simply create a new subdirectory (eg. for the new version without disturbing any running instances of your app. Again, if you obtain Omaha from us, we provide you with a launcher and an installer that obeys this structure.