Skip to content

Auto Update

See publish configuration for information on how to configure your local or CI environment for automated deployments.

Code signing is required on macOS

macOS application must be signed in order for auto updating to work.

Auto-updatable Targets

  • macOS: DMG.
  • Linux: AppImage.
  • Windows: NSIS.

All these targets are default, custom configuration is not required. (Though it is possible to pass in additional configuration, e.g. request headers.)

Squirrel.Windows is not supported

Simplified auto-update is supported on Windows if you use the default NSIS target, but is not supported for Squirrel.Windows. You can easily migrate to NSIS.

Differences between electron-updater and built-in autoUpdater

  • Dedicated release server is not required.
  • Code signature validation not only on macOS, but also on Windows.
  • All required metadata files and artifacts are produced and published automatically.
  • Download progress and staged rollouts supported on all platforms.
  • Different providers supported out of the box (GitHub Releases, Amazon S3, DigitalOcean Spaces, Bintray and generic HTTP(s) server).
  • You need only 2 lines of code to make it work.

Quick Setup Guide

  1. Install electron-updater as an app dependency.

  2. Configure publish.

  3. Use autoUpdater from electron-updater instead of electron:

    ```js tab=”JavaScript” const { autoUpdater } = require(“electron-updater”)

    ```js tab="ES2015"
    import { autoUpdater } from "electron-updater"

  4. Call autoUpdater.checkForUpdatesAndNotify(). Or, if you need custom behaviour, implement electron-updater events, check examples below.


  1. Do not call setFeedURL. electron-builder automatically creates app-update.yml file for you on build in the resources (this file is internal, you don’t need to be aware of it).
  2. zip target for macOS is required for Squirrel.Mac, otherwise latest-mac.yml cannot be created, which causes autoUpdater error. Default target for macOS is dmg+zip, so there is no need to explicitly specify target.


Example in TypeScript using system notifications

import { autoUpdater } from "electron-updater"

export default class AppUpdater {
  constructor() {
    const log = require("electron-log")
    log.transports.file.level = "debug"
    autoUpdater.logger = log

Custom Options instantiating updater Directly

If you want to more control over the updater configuration (e.g. request header for authorization purposes), you can instantiate the updater directly.

import { NsisUpdater } from "electron-updater"
// Or MacUpdater, AppImageUpdater

export default class AppUpdater {
    constructor() {
        const options = {
            requestHeaders: {
                // Any request headers to include here
                Authorization: 'Basic AUTH_CREDS_VALUE'
            provider: 'generic',
            url: ''

        const autoUpdater = new NsisUpdater(options)

Note: When you use autoUpdater from electron-updater there is some logic there to select which updater to use, you could mimic that logic to support multiple platforms. For example, checking the value of process.platform:

import { AppImageUpdater, MacUpdater, NsisUpdater } from "electron-updater"

const options = {  }

if (process.platform === "win32") {
    autoUpdater = new NsisUpdater(options)
else if (process.platform === "darwin") {
    autoUpdater = new MacUpdater(options)
else {
    autoUpdater = new AppImageUpdater(options)


You don’t need to listen all events to understand what’s wrong. Just set logger. electron-log is recommended (it is an additional dependency that you can install if needed).

autoUpdater.logger = require("electron-log")
autoUpdater.logger.transports.file.level = "info"

Note that in order to develop/test UI/UX of updating without packaging the application you need to have a file named dev-app-update.yml in the root of your project, which matches your publish setting from electron-builder config (but in yaml format). But it is not recommended, better to test auto-update for installed application (especially on Windows). Minio is recommended as a local server for testing updates.


Generated metadata files format changes from time to time, but compatibility preserved up to version 1. If you start a new project, recommended to set electronUpdaterCompatibility to current latest format version (>= 2.16).

Option electronUpdaterCompatibility set the electron-updater compatibility semver range. Can be specified per platform.

e.g. >= 2.16, >=1.0.0. Defaults to >=2.15

  • 1.0.0 latest-mac.json
  • 2.15.0 path
  • 2.16.0 files

Staged Rollouts

Staged rollouts allow you to distribute the latest version of your app to a subset of users that you can increase over time, similar to rollouts on platforms like Google Play.

Staged rollouts are controlled by manually editing your latest.yml / latest-mac.yml (channel update info file).

version: 1.1.0
path: TestApp Setup 1.1.0.exe
sha512: Dj51I0q8aPQ3ioaz9LMqGYujAYRbDNblAQbodDRXAMxmY6hsHqEl3F6SvhfJj5oPhcqdX1ldsgEvfMNXGUXBIw==
stagingPercentage: 10

Update will be shipped to 10% of userbase.

If you want to pull a staged release because it hasn’t gone well, you must increment the version number higher than your broken release. Because some of your users will be on the broken 1.0.1, releasing a new 1.0.1 would result in them staying on a broken version.

File Generated and Uploaded in Addition

latest.yml (or latest-mac.yml for macOS, or latest-linux.yml for Linux) will be generated and uploaded for all providers except bintray (because not required, bintray doesn’t use latest.yml).

Private GitHub Update Repo

You can use a private repository for updates with electron-updater by setting the GH_TOKEN environment variable (on user machine) and private option. If GH_TOKEN is set, electron-updater will use the GitHub API for updates allowing private repositories to work.


Private GitHub provider only for very special cases — not intended and not suitable for all users.


The GitHub API currently has a rate limit of 5000 requests per user per hour. An update check uses up to 3 requests per check.


The autoUpdater object emits the following events:

Event: error

  • error Error

Emitted when there is an error while updating.

Event: checking-for-update

Emitted when checking if an update has started.

Event: update-available

Emitted when there is an available update. The update is downloaded automatically if autoDownload is true.

Event: update-not-available

Emitted when there is no available update.

Event: download-progress

  • progress ProgressInfo
  • bytesPerSecond
  • percent
  • total
  • transferred

Emitted on progress.

Event: update-downloaded


AppUpdater ⇐ EventEmitter

Kind: class of electron-updater
Extends: EventEmitter Properties

  • autoDownload = true Boolean - Whether to automatically download an update when it is found.
  • autoInstallOnAppQuit = true Boolean - Whether to automatically install a downloaded update on app quit (if quitAndInstall was not called before).

    Applicable only on Windows and Linux.

  • allowPrerelease = false Boolean - GitHub provider only. Whether to allow update to pre-release versions. Defaults to true if application version contains prerelease components (e.g. 0.12.1-alpha.1, here alpha is a prerelease component), otherwise false.

    If true, downgrade will be allowed (allowDowngrade will be set to true).

  • fullChangelog = false Boolean - GitHub provider only. Get all release notes (from current version to latest), not just the latest.

  • allowDowngrade = false Boolean - Whether to allow version downgrade (when a user from the beta channel wants to go back to the stable channel).

    Taken in account only if channel differs (pre-release version component in terms of semantic versioning).

  • currentVersion SemVer - The current application version.

  • channel String - Get the update channel. Not applicable for GitHub. Doesn’t return channel from the update configuration, only if was previously set.
  • requestHeaders [key: string]: string - The request headers.
  • logger Logger - The logger. You can pass electron-log, winston or another logger with the following interface: { info(), warn(), error() }. Set it to null if you would like to disable a logging feature.
  • signals = new UpdaterSignal(this) UpdaterSignal - For type safety you can use signals, e.g. autoUpdater.signals.updateDownloaded(() => {}) instead of autoUpdater.on('update-available', () => {})



Asks the server whether there is an update.

appUpdater.checkForUpdatesAndNotify()Promise< | UpdateCheckResult>

Asks the server whether there is an update, download and notify if update available.


Start downloading update manually. You can use this method if autoDownload option is set to false.

Returns: Promise<Array<string>> - Where the first item in the list is guaranteed to be the path to downloaded file.

  • cancellationToken CancellationToken

appUpdater.getFeedURL()undefined | null | String appUpdater.setFeedURL(options)

Configure update provider. If value is string, GenericServerOptions will be set with value as url. (getter and setter)

Define the channel which the Auto-Updater will follow (see the auto-update with channels tutorial) using = 'beta' or get the current channel with currentChannel =

Please note that if you update this property then allowDowngrade will automatically be set to true. If you do not want this behaviour then you can change allowDowngrade after the channel property is set.

appUpdater.quitAndInstall(isSilent, isForceRunAfter)

Restarts the app and installs the update after it has been downloaded. It should only be called after update-downloaded has been emitted.

Note: Like Electron’s built-in quitAndInstall method, autoUpdater.quitAndInstall() will close all application windows first and only emit before-quit event on app after that. This is different from the normal quit event sequence (i.e. not during an update). As a result you should listen to Electron’s before-quit-for-update event (on electron.autoUpdater) if you wish to perform actions before the windows are closed while a process is quitting, as well as listening to before-quit. However, that is not the case for the (Windows) NSIS or (Linux) AppImage targets. The before-quit-for-update event is not emitted. The before-quit event is emitted first, then windows will be closed.

  • isSilent Boolean - windows-only Runs the installer in silent mode. Defaults to false.
  • isForceRunAfter Boolean - Run the app after finish even on silent install. Not applicable for macOS. Ignored if isSilent is set to false.


Kind: interface of electron-updater


  • message String


  • message any

  • message any


  • message any


Kind: interface of electron-updater

  • version String - The version.
  • files Array<module:builder-util-runtime.UpdateFileInfo>
  • path String - Deprecated: {tag.description}
  • sha512 String - Deprecated: {tag.description}
  • releaseName String - The release name.
  • releaseNotes String | Array<module:builder-util-runtime.ReleaseNoteInfo> - The release notes. List if updater.fullChangelog is set to true, string otherwise.
  • releaseDate String - The release date.
  • stagingPercentage Number - The staged rollout percentage, 0-100.


Kind: interface of electron-updater

  • updateInfo module:builder-util-runtime.UpdateInfo
  • downloadPromise Promise<Array<String>>
  • cancellationToken CancellationToken
  • versionInfo module:builder-util-runtime.UpdateInfo - Deprecated: {tag.description}



Emitted when an authenticating proxy is asking for user credentials.

  • handler - callback


  • handler - callback


  • handler - callback


  • handler - callback