electron-updater: auto updates for Electron apps
electron-updater is the auto-update library from the electron-builder project. It checks a file on a server, downloads the new version and installs it. Here's how to set it up, what the update files contain, and how to send updates only to paying customers.
electron-updater is the library most Electron apps use to update themselves. It's part of the electron-builder project. Your app asks a server "is there a newer version?", downloads it in the background if there is, and installs it when the user quits or when you tell it to.
The whole setup is three parts: a publish setting that says where your updates live, two lines of code in your main process, and a small YAML file on the server that electron-builder writes for you.
This guide covers the stable release line, electron-updater 6.x with electron-builder 26, which is what npm install gives you as of November 17, 2026. Version 7 is in alpha and changes a few things; there's a section on that near the end.
electron-updater vs Electron's built-in autoUpdater
Electron ships its own autoUpdater module, built on the Squirrel framework. It works, and it has limits: Electron's documentation says only macOS and Windows are supported, with no built-in support for Linux.
electron-updater replaces it. The differences its documentation lists:
- Linux is supported, as well as macOS and Windows
- The code signature is validated on Windows too, where the built-in updater only does that on macOS
- The update metadata files are produced and published for you
- Download progress and staged rollouts work on every platform
- It works with GitHub Releases, Amazon S3, DigitalOcean Spaces, Keygen, or any plain HTTPS server
The last one matters most. You don't need a dedicated update server, only somewhere that serves files.
What can be auto-updated
| Platform | Targets that update | Notes |
|---|---|---|
| macOS | DMG | The app must be signed, and you must also build the zip target |
| Windows | NSIS | Squirrel.Windows isn't supported |
| Linux | AppImage, DEB, Pacman, RPM |
Two things in that table catch people out.
On macOS, the update itself is delivered as a zip even though your customers first install from a DMG. electron-builder's default macOS target is dmg plus zip for this reason, and if you override the targets and leave zip out, the latest-mac.yml file can't be created.
And the macOS app has to be code signed, or the update is refused. That means a Developer ID certificate and, for the first download to open cleanly, notarization. The page on the "app is damaged" message covers what happens when that goes wrong.
Set it up
1. Install it
electron-updater runs inside your app, so it's a regular dependency, not a dev dependency:
npm install electron-updater
2. Say where updates are published
Add a publish block to your electron-builder configuration. For GitHub Releases:
publish:
provider: github
owner: your-name
repo: your-app
For any HTTPS server or storage bucket, use the generic provider with the base URL of the folder that holds your update files:
publish:
provider: generic
url: https://example.com/auto-updates
If your configuration lives in package.json, the same thing goes under build:
{
"build": {
"publish": [{ "provider": "generic", "url": "https://example.com/auto-updates" }]
}
}
When you build, electron-builder writes this into a file called app-update.yml inside the app's resources. That's how the installed app knows where to look, and it's why the documentation tells you not to call setFeedURL yourself.
3. Check for updates in the main process
const { autoUpdater } = require("electron-updater")
app.whenReady().then(() => {
autoUpdater.checkForUpdatesAndNotify()
})
That's the complete minimum. checkForUpdatesAndNotify() checks the feed, downloads a newer version if there is one, shows a system notification when it's ready, and installs it when the app quits.
If your main process uses ES modules, the import needs a workaround, because electron-updater is a CommonJS package:
import electronUpdater from "electron-updater"
const { autoUpdater } = electronUpdater
4. Turn on logging
Updates fail silently unless you log them. The documentation recommends electron-log:
autoUpdater.logger = require("electron-log")
autoUpdater.logger.transports.file.level = "info"
Do this before you ship. When a customer says "it never updates", the log file is the only way to find out why.
5. Build and publish
npx electron-builder --publish always
With the GitHub, S3 or Spaces providers, electron-builder uploads the installers and the metadata files. With the generic provider it only builds them: its documentation says you have to upload the application and metadata files yourself.
The update files: latest.yml
For each release, electron-builder produces a small metadata file next to your installers:
latest.ymlfor Windowslatest-mac.ymlfor macOSlatest-linux.ymlfor Linux
It looks like this:
version: 1.4.0
files:
- url: MyApp-Setup-1.4.0.exe
sha512: sKyuTCPCWsRD9WxOw2lOB/q0AhIarj3kkDoIo1K3kKEAv9NCP4b/LFFDtvhU5EYFNAHKO/MeYIAXvIVEzgdEqQ==
size: 91820432
path: MyApp-Setup-1.4.0.exe
sha512: sKyuTCPCWsRD9WxOw2lOB/q0AhIarj3kkDoIo1K3kKEAv9NCP4b/LFFDtvhU5EYFNAHKO/MeYIAXvIVEzgdEqQ==
releaseDate: '2026-11-17T10:00:00.000Z'
The installed app downloads this file, compares version with its own, and if the feed is newer it downloads the file named in files and checks it against the sha512. The URLs are relative, so the installer has to sit in the same folder as the YAML file.
An update, then, is two uploads: the new installer and the new latest.yml. If you upload the installer and forget the YAML, nobody gets the update. If you upload the YAML first, apps that check in between get a 404.
Controlling the update flow
checkForUpdatesAndNotify() is fine to start with. When you want your own "A new version is ready, restart now?" prompt, use the events:
autoUpdater.on("update-available", (info) => {
// info.version is the new version
})
autoUpdater.on("download-progress", (progress) => {
// progress.percent, progress.bytesPerSecond, progress.transferred, progress.total
})
autoUpdater.on("update-downloaded", (info) => {
// Ask the user, then:
autoUpdater.quitAndInstall()
})
autoUpdater.on("error", (error) => {
// Log it. Don't show raw errors to users.
})
autoUpdater.checkForUpdates()
The other events are checking-for-update, update-not-available and update-cancelled.
The settings you're most likely to change:
| Setting | Default | What it does |
|---|---|---|
autoDownload |
true |
Download an update as soon as it's found. Set it to false to ask first, then call downloadUpdate() |
autoInstallOnAppQuit |
true |
Install a downloaded update when the app quits |
allowPrerelease |
false |
GitHub provider only: also offer pre-release versions |
allowDowngrade |
false |
Allow moving to a lower version, which matters when switching channels |
channel |
latest |
Which update channel to follow, for example beta |
Only call quitAndInstall() after update-downloaded has fired.
Release channels and staged rollouts
Channels let some users get beta builds. Give a build a version like 1.5.0-beta.1, turn on generateUpdatesFilesForAllChannels in your build configuration, and electron-builder writes a beta.yml alongside latest.yml. In the app, opt a user in with:
autoUpdater.channel = "beta"
Users on the beta channel also get the stable releases.
Staged rollouts let you ship to a fraction of users first. Add one line to the published latest.yml:
stagingPercentage: 10
The update then goes to 10% of your users. Raise the number as you gain confidence. If the release turns out to be broken, you can't just pull it: the documentation says you must publish a new release with a higher version number, since the users who already updated won't move backwards.
Private updates: only for paying customers
Everything above assumes anyone can download your updates. If you sell the app, you may want updates to go only to customers with a valid license, particularly if you charge for major versions or sell subscriptions.
electron-updater supports this with request headers. Add an authorization header before checking, and it's sent with the request for the feed and for the download:
autoUpdater.addAuthHeader(`Bearer ${licenseKey}`)
autoUpdater.checkForUpdates()
Your server then has to check that token on every request and return the feed only when the license is valid. That's the part you'd have to build: a server that knows about licenses, serves the right latest.yml to each platform, and hands out download links.
LicenseSeat does that for you. You upload each release, and it serves the electron-updater feed for your product. The configuration is the generic provider pointed at your product:
publish:
provider: generic
url: https://licenseseat.com/p/<product-slug>/electron
With the feed set to licensed, a request without a valid license key gets an empty feed, so a customer whose subscription lapsed or who was refunded stops receiving new versions, while the version they have keeps working. The release notes you write appear in the update, and staged rollouts are supported. The guide to shipping desktop updates has the details. LicenseSeat charges a flat monthly fee and takes 0% of your revenue.
Testing updates
Auto-update doesn't run in development by default, because an unpackaged app has no app-update.yml. To try it, put a file called dev-app-update.yml in the root of your project with the same contents as your publish setting, and add:
autoUpdater.forceDevUpdateConfig = true
The documentation is honest that this isn't the recommended way to test, and that it's better to test with an installed application, especially on Windows. The test that tells you the truth is:
- Build and install version 1.0.0
- Publish version 1.0.1 to your feed
- Open the installed 1.0.0 and watch the log
Do it on each platform you ship. macOS and Windows fail in different ways.
Common errors
"Cannot find latest.yml" or a 404 on the feed. The YAML isn't where the app is looking. Open the URL from your publish setting plus /latest.yml in a browser. On macOS the file is latest-mac.yml, and it only exists if you built the zip target.
Updates never arrive on macOS. The app isn't signed, or the signature is invalid. Squirrel.Mac refuses unsigned updates.
"...is not signed by the application owner" on Windows. electron-updater checks that the new installer is signed by the same publisher as the installed app. This appears when you changed certificates, or when a release went out unsigned. If your publisher name changed, list both names under win.publisherName. The pages on SignTool and Azure Trusted Signing cover signing itself.
sha512 checksum mismatch. The installer on the server isn't the one the YAML describes. Usually the installer was re-signed or rebuilt after the YAML was generated, or a CDN is serving an older file. Sign before the metadata is generated, and upload both files from the same build.
"APPIMAGE env is not defined". On Linux, updates only work when the app runs as an AppImage. You'll see this when running the unpacked build.
Building with Tauri instead? The Tauri updater guide covers the same ground for Tauri 2.
What changes in electron-updater 7
Version 7 is in alpha alongside electron-builder 27, and the default pages on electron-builder's documentation site already describe it. If you read the docs and something doesn't match your installed version, this is probably why. The changes that affect a setup like the one above:
- Publishing has to be explicit, with
--publish always - Update manifests are signed by default, with the public key embedded in the app
- Feeds must be HTTPS unless you opt out
- Credentials are only sent to the feed's own origin, and a new required setting controls which headers follow a redirect to another host
If you send a license key or token with update requests, read the version 7 notes before upgrading, since the last point changes how authorization headers travel.
Common questions about electron-updater
What is electron-updater?
It's an npm package from the electron-builder project that adds automatic updates to Electron apps on macOS, Windows and Linux. It reads a metadata file from a server, downloads the new version, verifies it and installs it.
What is the difference between electron-updater and autoUpdater?
autoUpdater is Electron's built-in module, based on Squirrel, and supports macOS and Windows. electron-updater is a separate package that also supports Linux, generates its own metadata, verifies signatures on Windows, and works with plain file hosting.
Does electron-updater need a server?
It needs somewhere to host files, not an update server. GitHub Releases, an S3 bucket, or any HTTPS host that can serve the installer and latest.yml is enough.
Does electron-updater require code signing?
On macOS, yes: the app must be signed for updates to work. On Windows it isn't strictly required, but electron-updater verifies the publisher of each update when the installed app is signed, and unsigned installers trigger SmartScreen warnings.
Where is latest.yml and what is it for?
electron-builder generates it in your output folder next to the installers, and it must be uploaded with them. It tells installed apps the latest version, the file to download and its checksum.
How often does electron-updater check for updates?
Only when you call it. checkForUpdatesAndNotify() checks once. For an app that stays open for days, call checkForUpdates() on a timer as well, every few hours for example.
Can I use electron-updater with Electron Forge?
electron-updater is designed around electron-builder's targets and metadata files. Apps built with Electron Forge normally use Electron's built-in autoUpdater with a Squirrel-compatible feed.
Can I restrict updates to licensed users?
Yes. Send the license key or a token as an authorization header with addAuthHeader, and have the server return the feed only for valid licenses. LicenseSeat provides that kind of license-aware feed for electron-updater.