Setting Up Auto-Updates

Auto-updates are enabled by the electron-updater package, which allows your application to automatically check for and install new versions. This guide covers the complete setup process.

How Auto-Updates Work

The auto-update process follows these steps:

Configure the package to build release metadata (latest.yml)
Electron builder uploads release targets and metadata files to the configured target
Your Electron application queries the publish server for new releases

Code signing is required on macOSmacOS applications must be code signed for auto-updating to work.

Auto-Updatable Targets

The following build targets support auto-updates out of the box:

macOS: DMG
Linux: AppImage, DEB, Pacman (beta), and RPM
Windows: NSIS

Squirrel.Windows is not supported. Use the default NSIS target instead. You can migrate to NSIS.
For macOS, the zip target is required for Squirrel.Mac to create latest-mac.yml. The default target is dmg+zip, so no explicit configuration is needed.

Differences from Built-in autoUpdater

The electron-updater package offers several advantages over Electron’s built-in auto-updater:

Linux support in addition to macOS and Windows
Code signature validation on both macOS and Windows
Automatic metadata generation - all required metadata files and artifacts are produced and published automatically
Download progress and staged rollouts supported on all platforms
Multiple providers supported out of the box:
- GitHub Releases
- Amazon S3
- DigitalOcean Spaces
- Keygen
- Generic HTTP(s) server
Simple integration - only 2 lines of code required

Quick Setup Guide

1. Install electron-updater

Install electron-updater as an app dependency:

npm install electron-updater
# or
yarn add electron-updater

2. Configure Publish Options

Configure the publish options in your electron-builder config depending on where you want to host your release files.

3. Build Your Application

Build your application and verify that the build directory contains the metadata .yml files next to the built application. For most publish targets, the build step will also upload the files automatically (except for generic server option, where you must upload manually).

4. Import autoUpdater

Use autoUpdater from electron-updater instead of electron:

const { autoUpdater } = require("electron-updater")

5. Check for Updates

Call autoUpdater.checkForUpdatesAndNotify() for simple automatic updates, or implement custom event handlers for more control.

Do not call setFeedURL. electron-builder automatically creates the app-update.yml file for you on build in the resources directory.

Basic Implementation

Simple Auto-Update with Notifications

import { autoUpdater } from "electron-updater"

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

Custom Implementation with Event Handlers

For more control over the update process, listen to specific events:

import { autoUpdater } from "electron-updater"
import log from "electron-log"

autoUpdater.logger = log
autoUpdater.logger.transports.file.level = "info"

autoUpdater.on('checking-for-update', () => {
  log.info('Checking for update...');
})

autoUpdater.on('update-available', (info) => {
  log.info('Update available.');
})

autoUpdater.on('update-not-available', (info) => {
  log.info('Update not available.');
})

autoUpdater.on('error', (err) => {
  log.error('Error in auto-updater. ' + err);
})

autoUpdater.on('download-progress', (progressObj) => {
  let log_message = "Download speed: " + progressObj.bytesPerSecond;
  log_message = log_message + ' - Downloaded ' + progressObj.percent + '%';
  log_message = log_message + ' (' + progressObj.transferred + "/" + progressObj.total + ')';
  log.info(log_message);
})

autoUpdater.on('update-downloaded', (info) => {
  log.info('Update downloaded');
  // Install update after download
  autoUpdater.quitAndInstall();
});

// Start checking for updates
autoUpdater.checkForUpdates();

Advanced Configuration

Custom Options with Direct Instantiation

For more control over the updater configuration (e.g., request headers for authorization):

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

export default class AppUpdater {
  constructor() {
    const options = {
      requestHeaders: {
        // Any request headers to include here
      },
      provider: 'generic',
      url: 'https://example.com/auto-updates'
    }

    const autoUpdater = new NsisUpdater(options)
    autoUpdater.addAuthHeader(`Bearer ${token}`)
    autoUpdater.checkForUpdatesAndNotify()
  }
}

Staged Rollouts

Staged rollouts allow you to distribute updates to a subset of users. Control this by editing your latest.yml / latest-mac.yml file:

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

This example ships the update to 10% of your userbase.

If you need to pull a staged release, you must increment the version number higher than your broken release. Some users will already be on the broken version, and releasing the same version number would leave them stuck.

API Reference

Properties

autoDownload

boolean

default:"true"

Whether to automatically download an update when it is found.

autoInstallOnAppQuit

boolean

default:"true"

Whether to automatically install a downloaded update on app quit (if quitAndInstall was not called before).

autoRunAppAfterInstall

boolean

default:"true"

Whether to run the app after finish install when the installer is NOT in silent mode.

allowPrerelease

boolean

default:"false"

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), otherwise false.If true, downgrade will be allowed (allowDowngrade will be set to true).

allowDowngrade

boolean

default:"false"

Whether to allow version downgrade (when a user from the beta channel wants to go back to the stable channel).Taken into account only if channel differs (pre-release version component in terms of semantic versioning).

disableDifferentialDownload

boolean

default:"false"

NSIS only Disable differential downloads and always perform full download of installer.

forceDevUpdateConfig

boolean

default:"false"

Allows developer to force the updater to work in “dev” mode, looking for “dev-app-update.yml” instead of “app-update.yml”.

Dev: path.join(this.app.getAppPath(), "dev-app-update.yml")
Prod: path.join(process.resourcesPath!, "app-update.yml")

Events

The autoUpdater object emits the following events:

`error`

error Error

Emitted when there is an error while updating.

`checking-for-update`

Emitted when checking if an update has started.

`update-available`

info UpdateInfo

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

`update-not-available`

info UpdateInfo

Emitted when there is no available update.

`download-progress`

progress ProgressInfo
- bytesPerSecond - Download speed in bytes per second
- percent - Progress percentage
- total - Total bytes
- transferred - Transferred bytes

Emitted on download progress.

`update-downloaded`

info UpdateInfo

Emitted when an update has been downloaded.

Methods

`checkForUpdates()`

Asks the server whether there is an update. Returns: Promise<UpdateCheckResult | null> - Returns null if the updater is disabled, otherwise info about the latest version.

`checkForUpdatesAndNotify()`

Checks for updates and shows a system notification when an update is downloaded. Returns: Promise<UpdateCheckResult | null>

`downloadUpdate(cancellationToken?)`

Start downloading update manually. Use this method if autoDownload option is set to false. Parameters:

cancellationToken - Optional cancellation token

Returns: Promise<Array<string>> - Paths to downloaded files.

`quitAndInstall(isSilent?, isForceRunAfter?)`

Restarts the app and installs the update after it has been downloaded. Should only be called after update-downloaded has been emitted. Parameters:

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.

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.

Examples

Complete example showing how to use electron-updater
Encapsulated manual update via menu

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.

Private GitHub provider is 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.

Compatibility

Generated metadata files format changes from time to time, but compatibility is preserved up to version 1. For new projects, set electronUpdaterCompatibility to the current latest format version (>= 2.16). Option electronUpdaterCompatibility sets the electron-updater compatibility semver range. Can be specified per platform. Examples: >= 2.16, >=1.0.0. Defaults to >=2.15

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

Generated Files

latest.yml (or latest-mac.yml for macOS, or latest-linux.yml for Linux) will be generated and uploaded for all providers except bintray.

Code Signing

Auto Update

Advanced

How Auto-Updates Work

Auto-Updatable Targets

Differences from Built-in autoUpdater

Quick Setup Guide

1. Install electron-updater

2. Configure Publish Options

3. Build Your Application

4. Import autoUpdater

5. Check for Updates

Basic Implementation

Simple Auto-Update with Notifications

Custom Implementation with Event Handlers

Advanced Configuration

Custom Options with Direct Instantiation

Staged Rollouts

API Reference

Properties

Events

`error`

`checking-for-update`

`update-available`

`update-not-available`

`download-progress`

`update-downloaded`

Methods

`checkForUpdates()`

`checkForUpdatesAndNotify()`

`downloadUpdate(cancellationToken?)`

`quitAndInstall(isSilent?, isForceRunAfter?)`

Examples

Private GitHub Update Repo

Compatibility

Generated Files

Build docs developers (and LLMs) love

Code Signing

Auto Update

Advanced

​How Auto-Updates Work

​Auto-Updatable Targets

​Differences from Built-in autoUpdater

​Quick Setup Guide

​1. Install electron-updater

​2. Configure Publish Options

​3. Build Your Application

​4. Import autoUpdater

​5. Check for Updates

​Basic Implementation

​Simple Auto-Update with Notifications

​Custom Implementation with Event Handlers

​Advanced Configuration

​Custom Options with Direct Instantiation

​Staged Rollouts

​API Reference

​Properties

​Events

​error

​checking-for-update

​update-available

​update-not-available

​download-progress

​update-downloaded

​Methods

​checkForUpdates()

​checkForUpdatesAndNotify()

​downloadUpdate(cancellationToken?)

​quitAndInstall(isSilent?, isForceRunAfter?)

​Examples

​Private GitHub Update Repo

​Compatibility

​Generated Files

Build docs developers (and LLMs) love

How Auto-Updates Work

Auto-Updatable Targets

Differences from Built-in autoUpdater

Quick Setup Guide

1. Install electron-updater

2. Configure Publish Options

3. Build Your Application

4. Import autoUpdater

5. Check for Updates

Basic Implementation

Simple Auto-Update with Notifications

Custom Implementation with Event Handlers

Advanced Configuration

Custom Options with Direct Instantiation

Staged Rollouts

API Reference

Properties

Events

`error`

`checking-for-update`

`update-available`

`update-not-available`

`download-progress`

`update-downloaded`

Methods

`checkForUpdates()`

`checkForUpdatesAndNotify()`

`downloadUpdate(cancellationToken?)`

`quitAndInstall(isSilent?, isForceRunAfter?)`

Examples

Private GitHub Update Repo

Compatibility

Generated Files