Abstract Class: AppUpdater

Extends

• TypedEmitter<AppUpdaterEvents, this>

Extended by

• BaseUpdater
• MacUpdater

Constructors

Constructor

protected new AppUpdater(options, app?): AppUpdater

Parameters

options

AllPublishOptions | null | undefined

app?

AppAdapter

Returns

AppUpdater

Overrides

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).constructor

Properties

_isUpdateSupported

protected _isUpdateSupported: VerifyUpdateSupport

---

_isUserWithinRollout

protected _isUserWithinRollout: VerifyUpdateSupport

---

_logger

protected _logger: Logger = console

---

_verifyUpdateFile

protected _verifyUpdateFile: VerifyUpdateFile = DEFAULT_VERIFY_UPDATE_FILE

---

allowDowngrade

allowDowngrade: boolean = false

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).

Default

false

---

allowPrerelease

allowPrerelease: boolean = 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, here alpha is a prerelease component), otherwise false.

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

---

allowUnverifiedLinuxPackages

allowUnverifiedLinuxPackages: boolean = true

Linux only. Whether to allow installing unverified (unsigned / failing-GPG) .deb and .rpm packages during auto-update.

electron-builder does not sign Linux packages, so this defaults to true to preserve working auto-updates: the package manager's signature/GPG checks are bypassed where a bypass flag exists (--allow-unauthenticated for the apt fallback, --allow-unsigned-rpm for zypper, --nogpgcheck for dnf/yum), which is the historical behavior.

What false enforces depends on the package manager used on the target system:

• dpkg (the default for .deb): no effect — dpkg performs no signature verification (a warning is logged); enforcing .deb signatures requires a debsig-verify/debsigs policy on the target system.
• apt (.deb fallback): --allow-unauthenticated is omitted.
• zypper: enforced — unsigned/untrusted packages fail to install.
• dnf/yum: enforced via --setopt=localpkg_gpgcheck=1 (local package files are not GPG-checked by default).
• bare rpm (fallback): cannot be enforced via the CLI (a warning is logged); admins must configure %_pkgverify_level signature on the target system.

pacman and AppImage targets are not affected by this option: pacman -U has no per-invocation bypass flag (local-file policy is LocalFileSigLevel in pacman.conf), and AppImage updates are verified only via the update-manifest checksum.

Default

true

---

app

protected readonly app: AppAdapter

---

autoDownload

autoDownload: boolean = true

Whether to automatically download an update when it is found.

Default

true

---

autoInstallEvent

autoInstallEvent: AutoInstallEvent = "onQuit"

When a downloaded update is automatically installed (if quitAndInstall was not called before).

• "onQuit" (default) — install on app quit by spawning the installer while the app exits.
• "onNextLaunch" — defer the install: any app quit persists an install-on-next-launch marker for the downloaded update; on the next launch the updater re-validates the cached installer against freshly fetched update info and installs it (see installPendingUpdateIfAvailable). This avoids the class of failures where the on-quit installer process is killed by the OS before it finishes — most notably Windows terminating the detached NSIS installer during session end (log off / shutdown / restart), which can leave the app uninstalled but not re-installed (see https://github.com/electron-userland/electron-builder/issues/7807). The automatic install at startup only runs for targets that can install without an elevation prompt: NSIS (per-user, isAdminRightsRequired === false) and AppImage. Linux package targets (deb, rpm, pacman) always elevate via pkexec/sudo, and NSIS per-machine installs trigger a UAC prompt, so for those the pending update is kept and installPendingUpdateIfAvailable() must be called explicitly at a moment the app controls.
• "manual" — never auto-install; the downloaded update stays cached until an explicit quitAndInstall().

"onNextLaunch" is planned to become the DEFAULT in v28 to resolve this class of bug once and for all.

Default

"onQuit"

---

autoRunAppAfterInstall

autoRunAppAfterInstall: boolean = true

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

Default

true

---

currentVersion

readonly currentVersion: SemVer

The current application version.

---

disableDifferentialDownload

disableDifferentialDownload: boolean = false

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

Default

false

---

disableWebInstallerDefault

protected disableWebInstallerDefault: boolean = true

---

downloadedUpdateHelper

protected downloadedUpdateHelper: DownloadedUpdateHelper | null = null

---

forceDevUpdateConfig

forceDevUpdateConfig: boolean = 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")

Default

false

---

fullChangelog

fullChangelog: boolean = false

GitHub provider only. Get all release notes (from current version to latest), not just the latest.

Default

false

---

previousBlockmapBaseUrlOverride

previousBlockmapBaseUrlOverride: string | null = null

The base URL of the old block map file.

When null, the updater will use the base URL of the update file to download the update. When set, the updater will use this string as the base URL of the old block map file. Some servers like github cannot download the old block map file from latest release, so you need to compute the old block map file base URL manually.

Default

null

---

requestHeaders

requestHeaders: OutgoingHttpHeaders | null = null

The request headers.

---

signals

readonly signals: UpdaterSignal

For type safety you can use signals, e.g. autoUpdater.signals.updateDownloaded(() => {}) instead of autoUpdater.on('update-available', () => {})

---

stagingUserIdPromise

protected readonly stagingUserIdPromise: Lazy<string>

---

updateInfoAndProvider

protected updateInfoAndProvider: UpdateInfoAndProvider | null = null

---

updateManifestPublicKey

updateManifestPublicKey: string | string[] | null = null

The Ed25519 public key(s) (PEM or base64 SPKI) trusted to have signed the update manifest — the install's trust list. A single string or an array of keys; a manifest is accepted when any listed key validates one of its signatures. When set (non-empty), overrides the updateManifestPublicKey value embedded in app-update.yml.

When at least one key is available (here or in config) the manifest signature is enforced and a download will not start unless verification succeeds. When no key is available, verification is skipped (opt-in) and a one-time warning is logged.

Accessors

autoInstallOnAppQuit

Get Signature

get autoInstallOnAppQuit(): boolean

Deprecated

Removed in v27 — use autoInstallEvent. This accessor is a compatibility shim and will be deleted in v28.

A boolean cannot express the three install timings, so autoInstallOnAppQuit was replaced rather than extended. Without this shim the property assignment silently no-ops on a plain object: an app that set autoInstallOnAppQuit = false to opt out of install-on-quit would keep the "onQuit" default and install on quit anyway — the exact opposite of what it asked for.

Returns

boolean

Set Signature

set autoInstallOnAppQuit(value): void

Parameters

value

boolean

Returns

void

---

channel

Get Signature

get channel(): string | null

Get the update channel. Doesn't return channel from the update configuration, only if was previously set.

Returns

string | null

Set Signature

set channel(value): void

Set the update channel. Overrides channel in the update configuration.

allowDowngrade will be automatically set to true. If this behavior is not suitable for you, simple set allowDowngrade explicitly after.

Parameters

value

string | null

Returns

void

---

disableWebInstaller

Get Signature

get disableWebInstaller(): boolean

Whether to block NSIS web-installer packages. Web installer files might not have signature verification, so they are disabled by default as of v27: a web-installer update is rejected with ERR_UPDATER_WEB_INSTALLER_DISABLED at download time, before an install on next launch, and at install time unless this is false.

NsisUpdater defaults it to false for installs made by an nsis-web installer built with electron-builder v27+ (resources/package-type marker). Set it to false explicitly only if you intentionally publish and rely on NSIS web-installer packages and your installs lack that marker.

Set it before the app is ready (e.g. right after creating the updater): with autoInstallEvent: "onNextLaunch" a pending web-installer update is checked against it when the app is ready, and rejected (its pending-install marker cleared) while it is true.

Default

true

Returns

boolean

Set Signature

set disableWebInstaller(value): void

Parameters

value

boolean

Returns

void

---

isUpdateSupported

Get Signature

get isUpdateSupported(): VerifyUpdateSupport

Allows developer to override default logic for determining if an update is supported. The default logic compares the UpdateInfo minimum system version against the os.release() with semver package

Returns

VerifyUpdateSupport

Set Signature

set isUpdateSupported(value): void

Parameters

value

VerifyUpdateSupport

Returns

void

---

isUserWithinRollout

Get Signature

get isUserWithinRollout(): VerifyUpdateSupport

Allows developer to override default logic for determining if the user is below the rollout threshold. The default logic compares the staging percentage with numerical representation of user ID. An override can define custom logic, or bypass it if needed.

Returns

VerifyUpdateSupport

Set Signature

set isUserWithinRollout(value): void

Parameters

value

VerifyUpdateSupport

Returns

void

---

isWebInstallerEnabledByApp

Get Signature

get protected isWebInstallerEnabledByApp(): boolean

Returns

boolean

---

logger

Get Signature

get logger(): Logger | null

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.

Returns

Logger | null

Set Signature

set logger(value): void

Parameters

value

Logger | null

Returns

void

---

netSession

Get Signature

get netSession(): Session

Returns

Session

---

verifyUpdateFile

Get Signature

get verifyUpdateFile(): VerifyUpdateFile

Allows developer to set custom logic for verifying an update file before it is allowed to become installable. When the verification fails, the file is deleted and electron-updater emits an ERR_UPDATER_INVALID_UPDATE_FILE error. The default behavior is a stub – immediately succeeds.

It runs on every path that can lead to an install:

• right after a fresh download, while the file still sits under a temporary name and before it is renamed into the updater cache under its real filename, so an unverified file can never be executed under its real name;
• when an update downloaded by an earlier session is reused from the updater cache;
• before an install-on-next-launch spawns the cached installer (see BaseUpdater).

The custom logic gets updateFilePath (the file to verify), originalUpdateFileName (its real filename), the optional packageFilePath of an NSIS web installer package, and the active cancellationToken when the verification belongs to a download.

Assigning null restores the default stub.

Returns

VerifyUpdateFile

Set Signature

set verifyUpdateFile(value): void

Parameters

value

VerifyUpdateFile | null | undefined

Returns

void

Methods

addAuthHeader()

addAuthHeader(token): void

Shortcut for explicitly adding auth tokens to request headers

Parameters

token

string

Returns

void

---

addListener()

addListener<U>(event, listener): this

Type Parameters

U

U extends keyof AppUpdaterEvents

Parameters

event

U

listener

AppUpdaterEvents[U]

Returns

this

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).addListener

---

checkForUpdates()

checkForUpdates(): Promise<UpdateCheckResult | null>

Asks the server whether there is an update.

Returns

Promise<UpdateCheckResult | null>

null if the updater is disabled, otherwise info about the latest version

---

checkForUpdatesAndNotify()

checkForUpdatesAndNotify(downloadNotification?): Promise<UpdateCheckResult | null>

Parameters

downloadNotification?

DownloadNotification

Returns

Promise<UpdateCheckResult | null>

---

differentialDownloadInstaller()

protected differentialDownloadInstaller(fileInfo, downloadUpdateOptions, installerPath, provider, oldInstallerFileName): Promise<boolean>

Parameters

fileInfo

ResolvedUpdateFileInfo

downloadUpdateOptions

DownloadUpdateOptions

installerPath

string

provider

Provider<any>

oldInstallerFileName

string

Returns

Promise<boolean>

---

dispatchError()

protected dispatchError(e): void

Parameters

e

Error

Returns

void

---

dispatchUpdateDownloaded()

protected dispatchUpdateDownloaded(event): void

Parameters

event

UpdateDownloadedEvent

Returns

void

---

doDownloadUpdate()

abstract protected doDownloadUpdate(downloadUpdateOptions): Promise<DownloadExecutorResult>

Parameters

downloadUpdateOptions

DownloadUpdateOptions

Returns

Promise<DownloadExecutorResult>

---

downloadRequestHeaders()

protected downloadRequestHeaders(url, downloadUpdateOptions, originUrl?): OutgoingHttpHeaders

Headers for a download from url: when the provider has a feedBaseUrl, the credential-bearing ones are dropped if url is on another origin than originUrl (the feed by default). null keeps them for every URL.

Parameters

url

URL

downloadUpdateOptions

DownloadUpdateOptions

originUrl?

URL

Returns

OutgoingHttpHeaders

---

downloadUpdate()

downloadUpdate(cancellationToken?): Promise<DownloadExecutorResult>

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

Parameters

cancellationToken?

CancellationToken = ...

Returns

Promise<DownloadExecutorResult>

The downloaded files: updateFile is the path to the downloaded update (installer, AppImage, zip, ...), packageFile is the path to the NSIS web installer package and is only set for web installers.

---

emit()

emit<U>(event, ...args): boolean

Type Parameters

U

U extends keyof AppUpdaterEvents

Parameters

event

U

args

...Parameters<AppUpdaterEvents[U]>

Returns

boolean

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).emit

---

eventNames()

eventNames<U>(): U[]

Type Parameters

U

U extends keyof AppUpdaterEvents

Returns

U[]

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).eventNames

---

executeDownload()

protected executeDownload(taskOptions): Promise<DownloadExecutorResult>

Parameters

taskOptions

DownloadExecutorTask

Returns

Promise<DownloadExecutorResult>

---

getFeedURL()

getFeedURL(): string | null | undefined

Returns

string | null | undefined

---

getMaxListeners()

getMaxListeners(): number

Returns

number

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).getMaxListeners

---

getOrCreateDownloadHelper()

protected getOrCreateDownloadHelper(): Promise<DownloadedUpdateHelper>

Returns

Promise<DownloadedUpdateHelper>

---

getUpdateInfoAndProvider()

protected getUpdateInfoAndProvider(): Promise<UpdateInfoAndProvider>

Returns

Promise<UpdateInfoAndProvider>

---

installPendingUpdateIfAvailable()

installPendingUpdateIfAvailable(): Promise<boolean>

Installs an update that a previous launch marked as pending (see autoInstallEvent: "onNextLaunch" and quitAndInstall({ waitUntilNextLaunch: true })), then quits the app.

The cached installer is never trusted blindly: a fresh update-info fetch is performed first and the cached file is validated against it (checksum, and code signature where applicable). The pending update is only installed when its version is an installable change from the running app — newer, or older when allowDowngrade is set (a loop guard, mirroring isUpdateAvailable); otherwise the pending state is cleared.

Unlike the automatic startup install, an explicit call is also allowed for targets whose install requires elevation: NSIS per-machine installations (isAdminRightsRequired === true) and Linux package targets (deb, rpm, pacman — installed via pkexec/sudo).

On macOS this resolves to false: Squirrel.Mac already stages downloaded updates natively and applies them when the app is relaunched after quit, so there is no pending-install state managed by electron-updater.

Returns

Promise<boolean>

true if a pending update was validated and its installation was initiated (the app will quit).

---

isUpdaterActive()

isUpdaterActive(): boolean

Returns

boolean

---

listenerCount()

listenerCount(type): number

Parameters

type

keyof AppUpdaterEvents

Returns

number

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).listenerCount

---

listeners()

listeners<U>(type): AppUpdaterEvents[U][]

Type Parameters

U

U extends keyof AppUpdaterEvents

Parameters

type

U

Returns

AppUpdaterEvents[U][]

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).listeners

---

off()

off<U>(event, listener): this

Type Parameters

U

U extends keyof AppUpdaterEvents

Parameters

event

U

listener

AppUpdaterEvents[U]

Returns

this

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).off

---

on()

on<U>(event, listener): this

Type Parameters

U

U extends keyof AppUpdaterEvents

Parameters

event

U

listener

AppUpdaterEvents[U]

Returns

this

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).on

---

once()

once<U>(event, listener): this

Type Parameters

U

U extends keyof AppUpdaterEvents

Parameters

event

U

listener

AppUpdaterEvents[U]

Returns

this

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).once

---

onUpdateAvailable()

protected onUpdateAvailable(updateInfo): void

Parameters

updateInfo

UpdateInfo

Returns

void

---

prependListener()

prependListener<U>(event, listener): this

Type Parameters

U

U extends keyof AppUpdaterEvents

Parameters

event

U

listener

AppUpdaterEvents[U]

Returns

this

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).prependListener

---

prependOnceListener()

prependOnceListener<U>(event, listener): this

Type Parameters

U

U extends keyof AppUpdaterEvents

Parameters

event

U

listener

AppUpdaterEvents[U]

Returns

this

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).prependOnceListener

---

quitAndInstall()

abstract quitAndInstall(options?): void

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

Note: 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.

Parameters

options?

QuitAndInstallOptions

See QuitAndInstallOptions. When omitted, the installer runs non-silent and the deferred install-on-next-launch flow is not used (same behavior as before the options object was introduced).

Returns

void

---

rawListeners()

rawListeners<U>(type): AppUpdaterEvents[U][]

Type Parameters

U

U extends keyof AppUpdaterEvents

Parameters

type

U

Returns

AppUpdaterEvents[U][]

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).rawListeners

---

removeAllListeners()

removeAllListeners(event?): this

Parameters

event?

keyof AppUpdaterEvents

Returns

this

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).removeAllListeners

---

removeListener()

removeListener<U>(event, listener): this

Type Parameters

U

U extends keyof AppUpdaterEvents

Parameters

event

U

listener

AppUpdaterEvents[U]

Returns

this

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).removeListener

---

setFeedURL()

setFeedURL(options): void

Configure update provider. If value is string, GenericServerOptions will be set with value as url.

Parameters

options

PublishConfiguration | AllPublishOptions

If you want to override configuration in the app-update.yml.

Returns

void

---

setMaxListeners()

setMaxListeners(n): this

Parameters

n

number

Returns

this

Inherited from

(EventEmitter as new () => TypedEmitter<AppUpdaterEvents>).setMaxListeners