Auto Update
Auto updates are enabled by the electron-updater package. Ideally, auto updates are configured to run in a CI pipeline to automatically provision new releases. See publish configuration for information on how to configure your local or CI environment for automated deployments.
Auto updates work as follows:
- You configure the package to build release metadata (
latest.yml) - Electron builder uploads the actual release targets and metadata files to the configured target (except for generic server, where you have to upload manually)
- You configure the Electron application to use auto-updates, which queries the publish server for possible new releases
Read the remainder of this guide to configure everything.
macOS application must be signed in order for auto updating to work.
Auto-updatable Targets
- macOS: DMG.
- Linux: AppImage, DEB, Pacman and RPM.
- 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.
ziptarget for macOS is required for Squirrel.Mac, otherwiselatest-mac.ymlcannot be created, which causesautoUpdatererror. Default target for macOS isdmg+zip, so there is no need to explicitly specify target.
Differences between electron-updater and built-in autoUpdater
The electron-updater package offers a different functionality compared to Electron's built-in auto-updater. Here are the differences:
- Linux is supported (not only macOS and Windows).
- 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, Cloudflare R2, Keygen and generic HTTP(s) server).
- You need only 2 lines of code to make it work.
Quick Setup Guide
-
Install electron-updater as an app dependency.
-
Configure the
publishoptions depending on where you want to host your release files. -
Build your application and check that the build directory contains the metadata
.ymlfiles next to the built application. For most publish targets, the building step will also upload the files, except for the generic server option, where you have to upload your built releases and metadata manually. -
Use
autoUpdaterfromelectron-updaterinstead ofelectron:CommonJS
const { autoUpdater } = require("electron-updater")ESM
import { autoUpdater } from "electron-updater"TypeScript
import electronUpdater, { type AppUpdater } from 'electron-updater';export function getAutoUpdater(): AppUpdater {// Using destructuring to access autoUpdater due to the CommonJS module of 'electron-updater'.// It is a workaround for ESM compatibility issues, see https://github.com/electron-userland/electron-builder/issues/7976.const { autoUpdater } = electronUpdater;return autoUpdater;} -
Set
autoUpdater.crossOriginHeaders, which is required and chooses the request headers sent to another origin (() => []sends none of yours), then callautoUpdater.checkForUpdatesAndNotify(). Or, if you need custom behaviour, implementelectron-updaterevents, check examples below.
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). Its feed is the first provider that receives the update manifest (publishAutoUpdate not false) in the publish settings of the targets that write update info — a target-level publish such as nsis.publish counts — see which settings become the auto-update feed.
Examples
import { autoUpdater } from "electron-updater"
export default class AppUpdater {
constructor() {
const log = require("electron-log")
log.transports.file.level = "debug"
autoUpdater.logger = log
// none of the app's request headers go to another origin than the update feed
autoUpdater.crossOriginHeaders = () => []
autoUpdater.checkForUpdatesAndNotify()
}
}
- A complete example showing how to use.
- An encapsulated manual update via menu.
Custom Options instantiating updater Directly
If you want 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
},
provider: 'generic',
url: 'https://example.com/auto-updates'
}
const autoUpdater = new NsisUpdater(options)
autoUpdater.addAuthHeader(`Bearer ${token}`)
// which request headers may go to another origin: here none, so Authorization stays on the feed's origin
autoUpdater.crossOriginHeaders = () => []
autoUpdater.checkForUpdatesAndNotify()
}
}
The headers in requestHeaders / addAuthHeader other than the ones autoUpdater.crossOriginHeaders keeps for a request (the same rule as on a cross-origin redirect) and the query string of the feed url are only sent to the feed's origin (scheme, host and port; as on redirects, an http → https upgrade of the feed host on the default ports keeps the headers and the feed query). With the generic, s3, spaces, r2, keygen, bitbucket, github and gitlab providers, an update file whose URL in latest*.yml is on another origin, and the blockmaps and differential range requests derived from it, are downloaded without them; such a URL keeps its own query string. A channel file on another origin (a GitLab release link to another host, or a channel that is a URL) is requested without them too. A blockmap is downloaded from ${url}.blockmap with the file URL's query string, so a pre-signed installer URL's signature does not fit it: set files[].blockMapUrl in latest*.yml to the blockmap's own (pre-signed) URL. A relative value resolves like url (against the feed URL); an absolute URL is used as-is, with its own host and query string. Either follows the same origin rule. With a blockMapUrl, the old version's blockmap comes from the local cache or from previousBlockmapBaseUrlOverride; when neither has it, that one update is downloaded in full, which fills the cache for the next one (the private GitHub and GitLab providers, which resolve files from the release assets, ignore blockMapUrl). With every provider, including custom ones, a URL that electron-updater resolves against the feed URL (such as files[].url or a blockmap) gets the feed query only on the feed's origin. Serve the update files from the feed origin (relative files[].url, the default) or use pre-signed URLs. Signed update manifests cover files[].url and packages.<arch>.path, so a pre-signed URL has to be in latest*.yml before it is signed (see Key storage). A custom provider (one that does not extend a built-in provider such as GenericProvider) returns its feed URL from Provider.feedBaseUrl, which is required: that origin gets every header, and every other origin only the headers crossOriginHeaders keeps, with the feed URL as the hop's from. The same rule applies to the provider's own httpRequest calls (for example an API request in getLatestVersion), the headers passed in httpRequest's headers argument included; their Accept is sent whatever crossOriginHeaders returns. A provider whose feedBaseUrl is not a URL (for example one written in plain JavaScript that leaves it out, or one that returns null) fails the update check with ERR_UPDATER_FEED_BASE_URL_NOT_DECLARED before any request:
class MyProvider extends Provider<UpdateInfo> {
get feedBaseUrl(): URL {
return new URL("https://updates.example.com/")
}
// getLatestVersion(), resolveFiles(), …
}
Custom downloaded-file verification
All updater classes inherit AppUpdater.verifyUpdateFile, which lets you run your own verification step on an update file before it is allowed to become installable.
If the verification fails, the update is aborted, the file is deleted and an ERR_UPDATER_INVALID_UPDATE_FILE error is emitted.
The hook runs on every path that can lead to an install, so a rejected file can never reach the installer:
| When | updateFilePath points to |
|---|---|
| Right after a fresh download | the file under a temporary name — it is renamed to originalUpdateFileName only after your verification succeeds, so an unverified file is never executable under its real name |
| An update downloaded by an earlier session and reused from the cache | the cached file, under its real name |
| Before an install-on-next-launch spawns the cached installer | the pending installer, under its real name |
Only the first case can quarantine the file under a temporary name; in the other two the bytes are already on disk under their real name from a previous session, and the hook is a re-verification of a file at rest. cancellationToken is set only when the verification belongs to a download.
For NSIS web installers, packageFilePath is also provided and points to the downloaded companion .7z package. It is omitted when no such package was downloaded.
This hook is generic and works across updater implementations. On Windows NSIS updates, the built-in Authenticode verification remains available separately as NsisUpdater.verifyUpdateFileAuthenticodeSignature, and both run — Authenticode first, then your hook.
import { NsisUpdater } from "electron-updater"
const updater = new NsisUpdater()
updater.verifyUpdateFile = async ({ updateFilePath, originalUpdateFileName, packageFilePath, cancellationToken }) => {
try {
// Example for your custom code, which can inspect the update file at `updateFilePath`,
// can use the expected filename `originalUpdateFileName`, and for NSIS web installers can also inspect
// the downloaded companion package at `packageFilePath`.
const signatureFile = getCorrespondingSignatureFile(originalUpdateFileName)
checkSignature(updateFilePath, signatureFile)
return { response: "success" }
}
catch (err) {
return { response: "failure", message: `${err}` }
}
}
// assigning null restores the default (a stub that always succeeds)
updater.verifyUpdateFile = null
A failure must carry a message; it is what the emitted error reports as the reason.
Install on Next Launch (Windows/Linux)
When a downloaded update is automatically installed is controlled by autoUpdater.autoInstallEvent ("manual" | "onQuit" | "onNextLaunch", default "onQuit"). With the default "onQuit", the update is installed when the app quits: the updater spawns the installer as a detached process while the app is exiting. If the quit happens because the OS session is ending (shutdown, reboot or log off on Windows), the OS can kill that installer mid-install and leave the app in a broken, partially-uninstalled state (#7807).
electron-updater mitigates this in two ways:
-
Session-end guard (always on). When the OS signals that the session is ending, the on-quit install is skipped and a warning is logged. The downloaded update stays cached and is installed on the next regular quit. Detection is best-effort:
powerMonitorshutdownon macOS/Linux, and theBrowserWindowsession-endevent on Windows (windowless, e.g. tray-only, apps cannot be covered on Windows). -
Install on next launch (opt-in). Instead of installing while quitting, persist the downloaded update and install it at the start of the next launch, when no session teardown can interrupt it:
autoUpdater.autoInstallEvent = "onNextLaunch"With this set, any app quit records the downloaded update as pending instead of spawning the installer. On the next launch the updater fetches fresh update info from your update server, re-validates the cached installer against it (checksum, and code signature on Windows), verifies the pending version is still an installable change (newer than the running app — or a downgrade when
allowDowngradeis enabled), then runs the installer silently and restarts the app. If validation fails or the version is no longer an installable change, the pending state is cleared and the app starts normally.Set
autoInstallEvent = "manual"to disable automatic installation entirely (the downloaded update stays cached until you callquitAndInstall()yourself).A single quit can also be deferred without setting the property:
autoUpdater.quitAndInstall({ isSilent: true, isForceRunAfter: true, waitUntilNextLaunch: true })The next launch installs that update automatically, as with
"onNextLaunch", whateverautoInstallEventis set to, except"manual": then install it withinstallPendingUpdateIfAvailable().You can also trigger the pending install explicitly (e.g. before opening your first window):
await autoUpdater.installPendingUpdateIfAvailable()The automatic install starts right after the app is
ready, once your ownreadyhandlers have run. Configure the updater (autoInstallEvent,setFeedURL,addAuthHeader,requestHeaders,crossOriginHeaders) before the app isreadyor synchronously in areadyhandler, not after anawaitin it. Its requests and redirects to another origin carry the headers thatautoUpdater.crossOriginHeaderskeeps, and fail without it. An explicitinstallPendingUpdateIfAvailable()call never runs at the same time as the automatic install: one waits for the other, and the update is installed once.
Per-target behavior
The automatic install at startup only runs for targets that can install the pending update without an elevation/authentication prompt. Targets that always elevate to install (deb/rpm/pacman via pkexec/sudo, per-machine NSIS via UAC) skip the automatic path with a log message and keep the pending update — call installPendingUpdateIfAvailable() explicitly at a moment your app controls to install those.
| Target | Automatic install at next launch | Explicit installPendingUpdateIfAvailable() |
|---|---|---|
| NSIS (per-user) | ✓ | ✓ |
NSIS (per-machine, isAdminRightsRequired) | skipped — would show a UAC prompt at startup | ✓ (UAC prompt) |
| AppImage | ✓ | ✓ |
| deb / rpm / pacman | skipped — package managers always elevate (pkexec/sudo) | ✓ (auth prompt) |
| macOS | n/a — Squirrel.Mac stages updates natively and applies them on relaunch | resolves false |
electron-builder sets isAdminRightsRequired in the update info of every per-machine nsis and nsis-web build (perMachine: true), including assisted installers (oneClick: false) and builds with differentialPackage: false, so their updates are started with elevate.exe and skipped by the automatic install at launch.
autoInstallEvent defaults to "onQuit"; "onNextLaunch" is planned to become the default in v28 to resolve this class of session-end corruption once and for all. macOS is unaffected: Squirrel.Mac natively stages downloaded updates and applies them on relaunch, without a killable installer process (there "onQuit" and "onNextLaunch" behave identically).
Deferring the install to the next launch moves the installer out of the session-end quit — the common #7807 trigger — but it does not make the install itself atomic. If the user launches the app while the OS is already shutting down or rebooting (for example, right before a scheduled restart fires), the automatic startup install spawns the same detached NSIS/AppImage installer, and the OS can still terminate it mid-write.
The session-end guard does not cover this launch window: it is wired into the on-quit path only, and on a fresh launch the shutdown / session-end signal generally arrives after the startup install has already been spawned, so it cannot reliably win the race. The probability is very low — it requires a deferred update, a launch inside the shutdown window, and the OS killing the installer mid-write — and macOS is immune (Squirrel.Mac swaps the app bundle atomically). The only complete fix for NSIS/AppImage is an atomic install, which is out of scope for this feature.
Debugging
You don't need to listen to 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).
In latest version you need force the updater to work in "dev" mode:
autoUpdater.forceDevUpdateConfig = true
autoUpdater.crossOriginHeaders = () => [] // required in dev runs too
If you see this in logs:
APPIMAGE env is not defined, current application is not an AppImage
you need to apply this workaround otherwise update won't continue:
process.env.APPIMAGE = path.join(__dirname, 'dist', `app_name-${app.getVersion()}.AppImage`)
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.
Testing against a local update server
- Loopback
httpworks as is. A feed onlocalhost,127.0.0.0/8or::1may use plainhttpwith no opt-in, e.g.url: http://localhost:8080indev-app-update.ymlor the publish configuration. - Another machine (LAN host or VM) is not loopback, so plain
httpto it fails withERR_UPDATER_INSECURE_FEED. Either serve it overhttpswith a certificate the test machine trusts (e.g. made with mkcert, its root CA installed on that machine), or setautoUpdater.allowInsecureFeed = !app.isPackagedfor a dev run. An installed test build is packaged, so it needshttps, or a loopback feed: keepurl: http://127.0.0.1:8080in its publish configuration and forward that port on the test machine to the server (for examplenetsh interface portproxyon Windows,socaton Linux, orssh -L). - A redirect from
httpstohttp(other than to loopback) is rejected withERR_UPDATER_INSECURE_FEED, and a redirect from another machine to a loopback host withERR_UPDATER_LOOPBACK_REDIRECT: point the feed straight at the URL that serves the files. - Set
autoUpdater.crossOriginHeadersin dev runs too.checkForUpdates()rejects withERR_UPDATER_CROSS_ORIGIN_HEADERS_NOT_CONFIGUREDwithout it, unpackaged or not.
import { app } from "electron"
import { autoUpdater } from "electron-updater"
autoUpdater.crossOriginHeaders = () => []
autoUpdater.allowInsecureFeed = !app.isPackaged // only for an http feed on another machine
autoUpdater.forceDevUpdateConfig = !app.isPackaged // reads dev-app-update.yml
await autoUpdater.checkForUpdates()
For a local S3 server, see Testing Auto-Update Locally with Minio.
Compatibility
The generated latest*.yml uses the files[] metadata format. The legacy top-level path/sha512 fields, which only electron-updater 1.x – 2.15.0 needs, are written only for an electronUpdaterCompatibility range that includes those versions.
The electronUpdaterCompatibility option sets the electron-updater compatibility semver range: the electron-updater versions your installed apps ship, which have to read the update files a build publishes (e.g. >=7, >=6, >=1.0.0). Can be specified per platform (e.g. win.electronUpdaterCompatibility). Defaults to >=7. The range decides:
- the
.blockmapformat: the binary map for a range that includes only electron-updater 7 and later, the JSON map (with a build warning) for a range that includes earlier versions; - the legacy fields emitted in addition to
files[]: the top-levelpath/sha512and the Windowssha2checksum for ranges intersecting<2.16.0, and the oldlatest-mac.jsonfor ranges intersecting<2.0.0.
The build fails when the app's own electron-updater is outside the range of a platform it builds (for example electron-updater 6 with the default >=7): upgrade it, or declare a range that includes it. The app's electron-updater is the one in dependencies, else in devDependencies (bundled by webpack, vite and the like), else, with two package.json files, in the development package.json. Where the build writes binary .blockmap files (an NSIS installer, a macOS zip), electron-updater 7.0.0-alpha.0 to 7.0.0-alpha.12, which cannot read it, fail the build as well: upgrade to 7.0.0-alpha.13 or later, or set blockmap to "v2".
Metadata format history:
1.0.0latest-mac.json2.15.0path2.16.0files
Update metadata validated only by the legacy SHA-256 sha2 checksum is deprecated: a build that writes it and an update validated with it log a warning, and v28 is planned to reject it (fail-closed). Avoid pinning electronUpdaterCompatibility to a legacy range unless you actually ship 1.x–2.15 clients.
Update security options
The AppUpdater settings below protect the update path. See the Security & Hardening page for the full rationale.
The update manifest (latest*.yml) itself is cryptographically signed and verified before any download. Publishing a build that emits update metadata fails unless an Ed25519 signing key resolves; updateManifest: false is the only opt-out — see Signed Update Manifests.
A channel file (latest*.yml) larger than 10 MiB fails the update check with ERR_UPDATER_RESPONSE_TOO_LARGE: it is read into memory and parsed before the manifest signature is verified. Release feeds and provider API responses (such as the GitHub releases feed or a list of releases) are not limited, since their size grows with the release history. To allow larger channel files, set maxUpdateInfoSize (in bytes) in the publish configuration, which electron-builder writes into app-update.yml so installed apps use it, or autoUpdater.maxUpdateInfoSize in the app, which overrides it. Both take a positive integer, or 0 for no limit.
On Windows, an update whose manifest signature is not verified against an updateManifestPublicKey is installed only when the ProductVersion of its NSIS installer equals the version of latest.yml (electron-builder writes both from the app version); otherwise it fails with ERR_UPDATER_INSTALLER_VERSION_MISMATCH. The comparison is an exact string match: a hand-written version: v1.2.3 does not match the ProductVersion 1.2.3. This applies when the installer's signature is verified against a publisherName (of app-update.yml, else autoUpdater.publisherName), also to an update marked for install on next launch before it is installed — see the v27 migration guide.
A full download of an update file (installer, zip, Linux package or web package) stops with ERR_UPDATER_DOWNLOAD_SIZE_EXCEEDED as soon as it receives more bytes than the size the manifest declares for that file. A file without a numeric size in the manifest is not limited. electron-builder writes the size of the files it generates, except for an NSIS installer built with nsis.differentialPackage: false and the nsis-web installer itself (its package has a size).
Changing a signing key or certificate that installs in the field already trust requires a transition release — see Key Rotation.
The manifest is parsed before its signature is checked, so electron-updater rejects a latest*.yml whose YAML aliases (&name / *name) expand to more than 100000 values plus key and string characters (or more than the file's length, if that is larger) with ERR_UPDATER_INVALID_UPDATE_INFO, with every built-in provider. A manifest without aliases is never rejected for its size. Aliases are counted while the manifest is loaded, including aliases inside a non-scalar mapping key (? [*a, *a]), which is expanded into a string as it is parsed. An alias counts at least as many characters as it adds to that string (an aliased timestamp, for example, about 60), so such a manifest is rejected before the string is built. See the v27 migration notes for manifests that a tool of your own writes or rewrites.
disableWebInstaller (defaults to true)
NSIS web installers download their full payload at install time from a manifest-supplied URL, which may not undergo signature verification. AppUpdater.disableWebInstaller defaults to true, so a web-installer update is not loaded unless you opt in.
Unless the flag is false, a web-installer update is rejected with ERR_UPDATER_WEB_INSTALLER_DISABLED — at download time (including an update already cached by a previous launch), before an install on next launch, and at install time.
Installs made by an nsis-web installer carry a resources/package-type marker, and NsisUpdater then defaults the flag to false automatically. Set it yourself only for web-installer installs without that marker (installed by an installer from electron-builder 26 or earlier, or with a custom script) or when switching an app from nsis to nsis-web:
import { NsisUpdater } from "electron-updater"
const updater = new NsisUpdater()
updater.disableWebInstaller = false // only if you intentionally ship a web installer
Set it before the app is ready, e.g. right after creating the updater, or synchronously in a ready handler: a web-installer update marked for install on next launch is checked against the flag right after the app is ready, once your own ready handlers have run, and rejected (its pending-install marker cleared) while the flag is true.
A web update cached by a previous launch, or pending an install on next launch, is used only if its web package still matches the freshly fetched manifest; otherwise it is discarded. The nsis-web installer itself verifies the package electron-updater passes to it and installs its own copy — see Web Installer. Once the app runs the version of that update, NsisUpdater removes the package from its pending cache directory at startup (app ready); the package of an update that is not installed yet, or whose install failed, is kept for the install or a retry. Because the manifest vouches for the web package, don't set updateManifest: false for nsis-web apps: signed update manifests cover its path, SHA-512 and size.
allowInsecureFeed (defaults to false)
Every request electron-updater sends — the update feed (app-update.yml or setFeedURL), the update files, blockmaps, differential range requests and every redirect they follow — must use https. A request over plain http, including an https request redirected to http, fails with ERR_UPDATER_INSECURE_FEED before anything is sent to that URL. Requests to a loopback host (localhost, 127.0.0.0/8, ::1) are allowed over http, so a local test server can serve updates over http. A redirect to a loopback host, over http or https, from a URL that is not on one fails with ERR_UPDATER_LOOPBACK_REDIRECT, whatever allowInsecureFeed is: a remote server cannot point the updater at the user's machine. The same goes for the unspecified address (0.0.0.0, [::]), IPv4-mapped loopback ([::ffff:127.0.0.1]), localhost. and *.localhost names; another host name that resolves to a loopback address is not detected. electron-builder warns during the build when the feed written to app-update.yml (a generic or custom publish url, a github protocol: "http" or an s3 endpoint) uses http to a host that is not loopback.
Serve your updates over https. allowInsecureFeed is meant for development, such as a local test server on another machine: tie it to app.isPackaged so it cannot ship enabled.
import { app } from "electron"
import { autoUpdater } from "electron-updater"
autoUpdater.allowInsecureFeed = !app.isPackaged // plain http in dev runs only
A packaged app with allowInsecureFeed set logs a warning once, the first time it loads update info (an update check, or the validation of an update pending install at launch), linking Update requests require https. Over http, anyone on the network path can tamper with the update information and files: only a signed update manifest and the code signature of the update protect them. Set it to true in a packaged app only for a feed that cannot be served over https.
With allowInsecureFeed, a server's authentication challenge on a request that is neither https nor to a loopback host is cancelled without emitting login, as its authenticity cannot be determined, and electron-updater logs a warning the first time. A proxy's challenge, and a server's on a loopback request, reach login as on https. For your login handler to answer a server, serve the feed and the update files over https.
allowUnverifiedLinuxPackages (defaults to true)
AppUpdater.allowUnverifiedLinuxPackages (default true) controls GPG signature enforcement when installing .rpm auto-updates. Because electron-builder does not sign Linux packages itself, the default is permissive; if you sign your rpm packages, set it to false to have dnf/yum and zypper verify their signature (a bare rpm install cannot enforce it and logs a warning):
import { autoUpdater } from "electron-updater"
autoUpdater.allowUnverifiedLinuxPackages = false
It does not verify a .deb: apt checks no signature on a local .deb file (with false it only refuses dependencies from unauthenticated repositories), and dpkg checks none at all. The updater logs a warning when the flag is false for a deb update.
electron-builder does not sign rpm packages, so with false sign them yourself after the build (for example with rpm --addsign). Signing changes the files, so the sha512 and size that the build wrote for them into the Linux update manifest (latest-linux*.yml) no longer match: update both for each signed file, then sign the manifest again with the key(s) the build signed it with. electron-builder sign-update-manifest --rehash does both (see Re-signing after a file changed; where electron-builder cannot run, use the script in Re-signing without electron-builder). Run electron-builder verify before you upload. A build with an rpm target that writes update info warns when a file of the app (in app.asar or the app directory, not in node_modules) contains allowUnverifiedLinuxPackages = false (or its minified form allowUnverifiedLinuxPackages=!1) and the app ships an electron-updater that has the property.
Linux update authenticity
electron-updater installs what latest-linux.yml describes once the download matches its sha512. When the app embeds an update manifest public key (updateManifestPublicKey in app-update.yml, or set at runtime), that key is the trust anchor: a manifest it does not verify is rejected. Without a key (an app built with updateManifest: false, or an older build), verification is skipped with a warning and the feed — the first provider in app-update.yml, or the URL passed to setFeedURL — is the trust anchor; the sha512 comes from the same feed, so whoever can change the files on the feed can serve an update with a matching checksum. Signed update manifests are required by default at build time, and electron-updater enforces them whenever the app embeds a key. What makes a Linux update authentic is a signed update manifest, not a package-manager flag:
- AppImage has no package signature check at all.
- deb gets no package-level signature check, whatever
allowUnverifiedLinuxPackagesis set to (see above). - rpm is verified by
dnf/yumandzypperonly if you sign your packages and setallowUnverifiedLinuxPackages = false. Your signing key must then be imported into the rpm keyring on the target system (rpm --import), or the update fails to install. - pacman gets no package-level signature check:
pacman -Uis given no.sigfile, so under the defaultLocalFileSigLevelnothing is checked.allowUnverifiedLinuxPackageshas no effect on it.
To add a package-level check of your own for AppImage, deb or pacman updates, verify the downloaded file in verifyUpdateFile.
Keep signed update manifests on for Linux apps (don't set updateManifest: false), and serve the feed over https: electron-updater rejects plain http update requests unless allowInsecureFeed is set, and over http only a signed manifest protects the update.
Don't pre-authorize the update install. deb, rpm and pacman updates are installed as root through an elevation helper such as pkexec or sudo, which asks the user to authenticate. A polkit rule or a sudoers NOPASSWD entry that skips that prompt for the package manager lets any process running as the user install any package as root, not only electron-updater with your update.
autoUpdater.crossOriginHeaders
autoUpdater.crossOriginHeaders decides the request headers sent on each request and redirect to another origin than the update feed: a redirect to another origin (such as a feed that redirects to a CDN), a download or channel file (latest*.yml) on another origin, the blockmaps and differential range requests of such a download and their redirects, and a private GitHub release asset or GitLab release link on another origin. It is required: set it before the first check, and before the app is ready when an update can be installed at the next launch.
A build that writes app-update.yml for an app that ships electron-updater warns when no file of the app (in app.asar or the app directory, not in node_modules) contains the string crossOriginHeaders. An app that bundles electron-updater into its own JavaScript contains that string anyway, so the build stays quiet for it; the check only catches an app that never mentions the property. If a dependency sets it for the app, check for updates once from a packaged build to confirm.
crossOriginHeaders: CrossOriginHeadersCallback | null // null by default
type CrossOriginHeadersCallback = (headerNames: string[], hop: CrossOriginHop) => string[]
interface CrossOriginHop {
readonly from: URL // the URL the headers are meant for: the update feed, or the URL that redirected
readonly to: URL // the URL on the other origin
}
It gets the lowercase names of the request headers about to be sent, never their values, and returns the names of the ones to send (case-insensitive). The feed's own origin (Provider.feedBaseUrl) gets every header without asking it. Private GitHub's feed is the GitHub API (api.github.com, or the Enterprise host), whose asset URLs its release lookup, channel file and downloads use: they get every header, the token too, and the storage the API redirects a download to gets only what your callback keeps. electron-updater exports both types.
import { autoUpdater } from "electron-updater"
// none of the app's headers go to another origin
autoUpdater.crossOriginHeaders = () => []
// a tenant header for your CDN, nothing for any other origin
autoUpdater.crossOriginHeaders = (headerNames, hop) => (hop.to.origin === "https://cdn.example.com" ? headerNames.filter(it => it === "x-tenant") : [])
- Headers the updater builds. The headers electron-updater sets for each request itself are sent whatever the callback returns: its default
User-Agent,Cache-Control, theAcceptit or the provider sets and, for differential downloads,Range. AUser-Agentof your own fromrequestHeadersgoes to another origin only when the callback keepsuser-agent. - Headers it leaves out stay on the original origin:
AuthorizationfromaddAuthHeader, yourrequestHeaders, a provider's token (private GitHub, GitLab) andx-user-staging-id, which electron-updater sends with update info requests for staged rollouts. - Required, packaged or not. Without a function,
checkForUpdates(),checkForUpdatesAndNotify()anddownloadUpdate()emiterrorand reject withERR_UPDATER_CROSS_ORIGIN_HEADERS_NOT_CONFIGUREDbefore any request, and so does each request or redirect to another origin, such as one of the install at launch of an update marked for the next launch, which keeps the update pending. An unpackaged app withoutforceDevUpdateConfig, whosecheckForUpdates()otherwise skips the check and resolvesnull, gets the same error, so a missing callback shows up in development: set it in dev runs too. - Fails closed. A callback that throws, or returns anything but an array of strings, fails that request, unsent, with
ERR_UPDATER_INVALID_CROSS_ORIGIN_HEADERS. Its message holds no header value. - Read at each hop, so a new function serves the next request.
- Announces what it leaves out. The first time a request to an origin goes without some of your headers or a provider's (never the updater's own), electron-updater logs a warning, once per origin, naming those headers and both origins (never a value), with a link to the migration guide.
- Compare the whole origin (
hop.to.origin, scheme and port included), nothop.to.hostname, so anhttpURL or another port on the same host does not get your headers.
See The app chooses the headers sent to another origin.
When the update host changes its redirects
Production updates can start failing with a 401 or 403, or a failed download, when the update host or its CDN starts redirecting to a new origin (a new CDN hostname or storage bucket): that origin gets only the headers your callback keeps for it.
-
Look at the warning. electron-updater logs one, once per origin, naming the headers your callback left out for that origin and both origins.
-
Look at the hops. The callback receives each hop: log
hop.from.originandhop.to.originwhile testing (origins, not full URLs, whose query can hold a signed token). WithDEBUG=electron-builder, the updater also logs a debug line for each cross-origin request naming the two hosts and the header names it sends, never their values. -
Allow specific headers only for origins you trust, keyed on
hop.to.origin. Never return all ofheaderNames: that sends your credentials to whatever origin the host redirects to.const allowed = new Map([["https://cdn.example.com", ["x-tenant"]]])autoUpdater.crossOriginHeaders = (headerNames, hop) => headerNames.filter(it => allowed.get(hop.to.origin)?.includes(it) ?? false) -
Test against a staging feed that redirects the way production will, before you roll out a new host, CDN or app release. Installed apps keep the callback they shipped with: until they update to a release that allows the new origin, keep serving them from an origin they allow, or from URLs that need none of your headers (such as pre-signed URLs).
Linux installs with gksudo, kdesudo or beesu
To install a deb, rpm or pacman update, electron-updater elevates the package manager with the first helper it finds: pkexec, then gksudo, kdesudo and beesu, else sudo. pkexec and sudo take the command as separate arguments, so any installer path works with them. gksudo, kdesudo and beesu take the install command as a single string that a shell and the helper parse again, so with one of them the path of the downloaded package (in the updater's cache directory, file name included) may only hold ASCII letters and digits, the characters . _ / + , : = @ % - (with kdesudo, a space too) and non-ASCII characters such as é, 中, ™, –, ’ or emoji. Non-ASCII control, format (such as bidi controls) and separator characters (such as a no-break space or U+2028) are not allowed. Any other path fails the install with ERR_UPDATER_UNSAFE_INSTALLER_PATH before the helper runs. Installing polkit, which provides pkexec, avoids this: electron-updater then elevates with pkexec whatever the path. See the migration note.
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 the stagingPercentage field of your latest.yml / latest-mac.yml (channel update info file), which electron-builder does not write itself.
version: 1.1.0
files:
- url: TestApp Setup 1.1.0.exe
sha512: Dj51I0q8aPQ3ioaz9LMqGYujAYRbDNblAQbodDRXAMxmY6hsHqEl3F6SvhfJj5oPhcqdX1ldsgEvfMNXGUXBIw==
size: 62021782
stagingPercentage: 10
Update will be shipped to 10% of userbase.
latest.yml again after changing stagingPercentageelectron-builder signs update manifests by default, and stagingPercentage is covered by the signature. Adding or changing it in a signed latest.yml by hand, without signing the file again, makes every install that embeds the public key reject the manifest with ERR_UPDATER_MANIFEST_SIGNATURE_INVALID: the release then reaches none of your users instead of 10% of them. The same applies to every later change, such as raising the percentage or setting it to 0 to pause the rollout. Only an unsigned manifest (updateManifest: false) can be edited by hand.
To set or change the percentage of a signed release, sign latest.yml again with the key(s) the release was signed with before you upload it. Edit stagingPercentage, then run electron-builder sign-update-manifest from the project directory; it takes the key(s) from the same configuration and environment variables as the build:
npx electron-builder sign-update-manifest dist/latest.yml
Where electron-builder cannot run, the script in Re-signing without electron-builder signs it with the same key(s); it takes the sha512 and size of every listed file from the release's files, so run it where they are next to latest.yml.
Then upload the signed latest.yml. While the build output is still at hand, electron-builder verify checks it against the key the packaged app embeds, and the files it lists against the artifacts.
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).
Differential updates: .blockmap
For targets that support differential (delta) updates (NSIS on Windows and the macOS update zip; AppImage embeds its map in the binary), electron-builder publishes a block map next to the artifact: a list of content-defined blocks and their hashes. electron-updater compares the new map with the one of the installed version and downloads only the byte ranges that changed, using HTTP Range requests.
One <artifact>.blockmap is published per artifact. Its format follows electronUpdaterCompatibility, since the map is read by the updater already installed in your users' apps:
"v3"(the default whenelectronUpdaterCompatibilityincludes only electron-updater 7 and later, as the default>=7does): an uncompressed binary map that electron-updater fetches in parts withRangerequests. It carries the blocks in a three-level layout (a small table of super-groups, a table of groups of blocks, then one 10-byte record per block), so the updater reads the super-group table, compares it with its cached previous map, fetches only the group entries of the super-groups that changed, compares those, and finally fetches only the records of the groups that changed. The map cost of an update therefore grows with the change, not with the installer size, which is what makes 512 B blocks insideapp.asaraffordable."v2"(the default when the range includes electron-updater 6 or earlier): the gzipped JSON map (~16 KiB blocks) every electron-updater release reads. It is downloaded in full on every update, a fixed cost of roughly 20 bytes per block of the installer. The build warns that it writes this format and why.
The blockmap option overrides the choice: "v2" always writes the JSON map, "v3" the binary map (the build fails when electronUpdaterCompatibility includes electron-updater versions before 7), and "latest" the newest format the range allows, so that a future format is picked up without a config change.
Compatibility: electron-updater tells the two formats apart by the file's first bytes, so latest.yml is the same for both. electron-updater before 7.0 cannot read "v3": an app still on electron-updater 6 that receives a release with a binary map falls back to a full download once ("Cannot download differentially, fallback to full download"), and the update it installs brings an updater that can. From electron-updater 6.8.10 the next update is differential again when the artifact name includes ${version}, as the default names do; 6.8.9 and earlier leave the old block map in their cache, which can make the next update a full download too. With an artifact name without the version (e.g. "${productName} Setup.${ext}") the transition costs two full downloads: electron-updater 6 caches no map for the release it could not read, and the URL electron-updater 7 derives for the installed version's map (the new map's URL with the version replaced) is then the new map's own, so the next update is downloaded in full as well and caches its map ("…because the artifact name has no version: downloading the full update"); the update after it is differential. Block maps embedded in an artifact (AppImage, the NSIS web installer's app package) are always "v2".
Switching formats between two releases (for example raising electronUpdaterCompatibility to >=7 in an app that wrote "v2" maps, or going back to "blockmap": "v2") does not cost a full download with electron-updater 7.0.0-alpha.14 and later. Both formats come from the same content-defined chunker and the same blake2b block digest: a "v2" map stores the whole digest and a "v3" map its first 8 bytes, so electron-updater compares a cached map of one format with the new map of the other by those 8 bytes, without reading or re-hashing the installed file ("Block map format changed (old: v2, new: v3): comparing the blocks by the v3 block hashes both maps carry", at info). The new map is downloaded whole that once, and the next update fetches it in parts. Blocks are cut the same way in both formats except inside a stored member: with nsis.differentialPackage: "store-asar", "v3" cuts the stored app.asar into 512 B to 2 KiB blocks where "v2" used 4 to 16 KiB ones, so that first update downloads the stored asar whole and copies everything else. A "v2" map whose checksums are not the digests electron-builder writes is not compared, and that update is downloaded in full ("…cannot be compared with a v3 map…: downloading this update in full"). Earlier electron-updater 7 prereleases download the first update after a format change in full. A future format under "latest" may cost one full download as well.
Compressed artifacts: a differential NSIS package (7z, non-solid, 1 MB dictionary) and a macOS zip (each file deflated on its own) are cut into the same 8/16/32 KiB blocks in both formats; only stored bytes get finer "v3" blocks. Compressed bytes change from the edit to the end of the compressed stream they belong to (one file of a zip, one 4 MB LZMA2 block of the package, or the whole deflated app.asar of a macOS zip), whatever the block size, so "v3" downloads the same data for them as "v2". What it changes is the map: about 10 bytes per block instead of about 22 for incompressible content, and only its changed parts are fetched. That is why "latest" and the default write "v3" for compressed artifacts too. To make app-code updates small, store the asar (below) rather than changing the block map format.
{
"electronUpdaterCompatibility": ">=7",
"blockmap": "v3"
}
The "v3" format pays off most for app-code changes when the asar is stored uncompressed and laid out so that a small edit does not shift the rest of the archive:
{
"nsis": { "differentialPackage": "store-asar" },
"asar": { "contentAlignment": 512 }
}
nsis.differentialPackage: "store-asar" stores resources/app.asar uncompressed in the differential package (so a one-line change maps to a few changed blocks instead of a re-compressed archive), and asar.contentAlignment pads file contents inside the asar so that a file growing by a few bytes does not move the offsets of every later file. The "v3" format additionally starts a new block at every packed file of the stored asar, so an edit inside one file never touches a block of its neighbour, and in a build that writes it the 7z header of every differential package is stored as is and chunked on its own, so the CRCs that change with each build cost a few hundred bytes instead of the package's last block (a "v2" build packages exactly as electron-builder 26 did). With all of that, the "v3" rows of the repository benchmark (test/src/differentialOneLineBenchTest.ts) bring a one-line change in a 32 MB asar down to about ten kilobytes on the wire.
How this compares with per-version delta packages (Squirrel, Velopack): those frameworks compute a binary patch between two specific releases on the build machine and publish one delta file per consecutive version pair, which a client applies in sequence from the exact release it has installed. The patch itself is small (a zstd --patch-from diff of a one-line change is a few kilobytes), but every release pair needs its own artifact, a client that skipped releases applies several of them, and the old release must still be present in full. A block map describes a single artifact independently of any previous version: one .blockmap per installer serves updates from any older version, the server only needs HTTP Range support, and the cost of an update is a handful of kilobytes of map plus the changed blocks. The repository benchmark reports both side by side for the same synthetic app.
electron-updater also downloads through small gaps between changed ranges (copy gaps below 8 KiB are fetched rather than copied, saving one request per gap on hosts such as GitHub or S3 that serve a single range per request) and never puts more than 200 ranges into one multipart/byteranges request (Apache's default MaxRanges).
A block map may be at most 1/16 of the update's size, no less than 8 MiB and no more than 64 MiB (64 MiB when the update's size is not known); a "v2" map, or one embedded in an artifact, is measured unzipped, and a block map's download stops as soon as it passes the limit. With a larger map, or a "v3" map that describes a file of another size than the update, the update is downloaded in full.
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.
Don't put the token in the publish configuration. Every option of the provider that becomes the feed is written in plain text to app-update.yml inside the packaged app (see which settings become the auto-update feed), where anyone with a copy of the app can read it. Set private: true and provide GH_TOKEN (or GITHUB_TOKEN) on the user's machine, or pass the token with setFeedURL({ provider: "github", owner, repo, token }). A token hard-coded in the app's code and passed to setFeedURL is as easy to extract as one in app-update.yml: a token provided at runtime has to be a per-user secret, such as one your server issues to a signed-in user.
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.
Events
The autoUpdater object emits the following events:
Event: error
errorError
Emitted when there is an error while updating.
Event: login
authInfoAuthInfocallbackFunction —callback(username, password); called without arguments, it cancels the authenticationurlString — the URL of the update request that got the challenge (after a redirect, the redirect's target)
Emitted when an update request gets an authentication challenge, from a proxy (authInfo.isProxy) or from a server. Call callback(username, password) to answer it, or callback() to cancel it; the request then fails with the challenge's status. Without a login listener, electron-updater cancels the challenge and logs a warning once, naming the challenger's host and port; a listener that throws cancels it too.
A challenge from any origin the updater requests reaches your handler: the feed, a download URL on another origin and the target of a redirect. Answer only the proxy or the server your credentials are meant for: give a proxy its own credentials after checking authInfo.host, answer a server only when the request's origin, new URL(url).origin, is your feed's (authInfo has no scheme), and call callback() for any other. A server's challenge from another origin than the feed logs a warning once when no handler takes the url argument.
const FEED_ORIGIN = "https://updates.example.com"
const PROXY_HOST = "proxy.corp.example"
autoUpdater.on("login", (authInfo, callback, url) => {
if (authInfo.isProxy) {
// the proxy's own credentials, never the feed's
authInfo.host === PROXY_HOST ? callback(proxyUsername, proxyPassword) : callback()
} else if (new URL(url).origin === FEED_ORIGIN) {
callback(feedUsername, feedPassword)
} else {
callback()
}
})
With allowInsecureFeed, a server's challenge on a request that is not https and not to a loopback host is cancelled without emitting login, as its authenticity cannot be determined; electron-updater logs a warning the first time. Serve the feed and the update files over https to answer it.
Event: checking-for-update
Emitted when checking if an update has started.
Event: update-available
infoUpdateInfo (for generic and github providers) Emitted when there is an available update. The update is downloaded automatically ifautoDownloadistrue.
Event: update-not-available
Emitted when there is no available update.
infoUpdateInfo (for generic and github providers)
Event: download-progress
progressProgressInfobytesPerSecondpercenttotaltransferred
Emitted on progress.
Event: update-downloaded
infoUpdateInfo — for generic and github providers.
Event: update-cancelled
infoUpdateInfo
Emitted when an update is cancelled by the user or the download is otherwise aborted.
Event: appimage-filename-updated
pathstring
Emitted after a successful AppImage update when the file is moved to its final location. Only fires on Linux AppImage builds.
UpdateInfo
Interface: UpdateInfo
Extended by
Properties
files
readonlyfiles:UpdateFileInfo[]
minimumSystemVersion?
readonlyoptionalminimumSystemVersion?:string
The minimum version of system required for the app to run. Sample value: macOS 23.1.0, Windows 10.0.22631.
Same with os.release() value, this is a kernel version.
path?
readonlyoptionalpath?:string
Legacy top-level download descriptor for electron-updater 1.x – 2.15.0. Modern clients read files.
Only emitted when electronUpdaterCompatibility includes legacy clients, so it may be absent.
Deprecated
releaseDate
releaseDate:
string
The release date.
releaseName?
optionalreleaseName?:string|null
The release name.
releaseNotes?
optionalreleaseNotes?:string|ReleaseNoteInfo[] |null
The release notes. List if updater.fullChangelog is set to true, string otherwise.
sha512?
readonlyoptionalsha512?:string
Legacy top-level checksum for electron-updater 1.x – 2.15.0. Modern clients read files[].sha512.
Only emitted when electronUpdaterCompatibility includes legacy clients, so it may be absent.
Deprecated
signature?
readonlyoptionalsignature?:string
Base64-encoded Ed25519 signature over the manifest's integrity-critical fields, populated at
publish time when update manifest signing is enabled. Verified by electron-updater against the
configured updateManifestPublicKey before any download starts. See canonicalizeForSigning.
Always the signature of the first configured signing key; signatures carries the same value
(tagged with its key id) plus one entry per additional signing key. Kept so updaters that only know
this single-signature form keep verifying.
signatures?
readonlyoptionalsignatures?:UpdateManifestSignature[]
One Ed25519 signature per signing key the manifest was signed with, each tagged with the id of the
key that produced it (see computeUpdateManifestKeyId). All entries sign the same canonical payload.
A manifest carrying several entries is "dual-signed": an install verifies it as long as any of its
trusted keys matches any entry, which is what makes key rotation possible without a flag day.
stagingPercentage?
readonlyoptionalstagingPercentage?:number
The staged rollout percentage, 0-100.
version
readonlyversion:string
The version.