Guide · Open source

How to use electron-builder: install, configure and package an Electron app

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

electron-builder is a tool that takes an Electron app, a desktop app built with web technologies, and packages it into distributable files for macOS, Windows and Linux. This guide shows you how to install it, configure a minimal build, run packaging scripts and know which formats and publishing options are available. By the end you will have a working packaging setup for your own Electron project.

electron-builderelectron-userland/electron-builder · ★ 14.7k · MIT Install options & downloads

Quick start

1Confirm prerequisites. Check that you have Node.js 22.12.0 or higher and an existing Electron project.
2Install the package. Run yarn add electron-builder --dev in your project folder.
3Set standard fields. Add name, description, version and author to package.json.
4Add a build config. Add a build key with appId and a mac category, then list files as needed.
5Add icons. Add the icons your target platforms need, following the project's icons documentation.
6Add packaging scripts. Add app:dir and app:dist scripts, then run yarn app:dist to produce a distributable.

What you need before you install electron-builder

electron-builder needs Node.js version 22.12.0 or higher for v27, and it is designed for projects that are already Electron apps. It only packages Electron projects, so you need an existing Electron app to work with.

Node.js >=22.12.0 (required for v27)
An Electron project; the official electron-quick-start is a minimal starter

Install electron-builder as a dev dependency

Add electron-builder to your project as a development dependency. The README shows Yarn, and notes that npm, pnpm and bun also work.

If you use Yarn 3, it defaults to PnP, but electron-builder still needs node-modules, so set the node linker in your Yarn configuration file.

Yarn 3 users: set nodeLinker to node-modules in .yarnrc.yaml

yarn add electron-builder --dev

Configure the build in package.json

Set the standard fields in your package.json: name, description, version and author. Then add a build key with at least an appId and, for macOS, a category.

The files option controls which files are packed into the final application, including the entry file, and may be required. Configuration can also live in separate files such as js, ts, yml, and json/json5 files.

Add icons (see the project's icons and images documentation)
Check the full options list at electron.build/docs/configuration

"build": {
  "appId": "your.id",
  "mac": {
    "category": "your.app.category.type"
  }
}

Add scripts to package your app

Add two scripts to package.json. The app:dist script creates a distributable format such as a dmg, Windows installer or deb package. The app:dir script only generates the unpacked package directory, which is useful for testing.

To keep native dependencies matched to your Electron version, add a postinstall script that runs install-app-deps. If you have your own native addons that are part of the application, set nativeModules.nodeGypRebuild to true.

Run yarn app:dist to build a distributable
Run yarn app:dir to generate an unpacked directory for testing

"scripts": {
  "app:dir": "electron-builder --dir",
  "app:dist": "electron-builder",
  "postinstall": "electron-builder install-app-deps"
}

Choose output formats and publish your builds

electron-builder supports many target formats. All platforms can get 7z, zip, tar.gz and an unpacked dir. macOS targets include dmg, pkg and mas. Linux targets include AppImage, snap, deb, rpm and pacman. Windows targets include nsis, nsis-web, portable, AppX, MSI and Squirrel.Windows.

The tool can publish artifacts to GitHub Releases, Amazon S3 and DigitalOcean Spaces. It also supports code signing on a CI server or development machine, and auto-update ready packaging.

To build Linux or Windows packages from another platform, the README points to Docker images.

Upgrading to v27 safely

v27 is a major release with breaking changes, including native ESM, Node >=22.12 and removed deprecated APIs. Read the What's New in v27 page and the breaking changes page before upgrading.

The README describes an automated command that rewrites your config in place. Back up your project first, and follow the v26 to v27 migration guide if you are coming from v26.

electron-builder migrate-schema

What people use it for

Shipping an Electron app as a dmg for macOS and an NSIS installer for Windows from one project
Producing AppImage or deb packages for Linux users
Publishing release builds to GitHub Releases, S3 or DigitalOcean Spaces from one tool
Building Windows or Linux packages on a macOS machine using the Docker images
Packaging an unpacked directory with yarn app:dir to test the app before a full release

Frequently asked questions

Is electron-builder free to use?

The project is released under the MIT licence, according to the repository. The README does not list any paid tier, so check the licence file in the repository for full terms.

What Node.js version does electron-builder need?

Version 27 requires Node.js 22.12.0 or higher. The README does not say which older Node.js versions are supported, so check the documentation before using an older setup.

How do I install electron-builder?

Run yarn add electron-builder --dev in your project. The README notes that npm, pnpm and bun also work. Yarn 3 users need to set nodeLinker to node-modules.

Can electron-builder create Windows installers on macOS or Linux?

The README says Docker images are available to build Electron apps for Linux or Windows on any platform. See the multi-platform build documentation for the steps.

Does electron-builder support auto-update?

Yes. The README says it produces auto-update ready application packaging, and links to an auto-update feature page for details.

How does electron-builder compare to electron-forge, electron-packager or Tauri?

This guide does not have a verified comparison. electron-forge, electron-packager and Tauri are listed as comparable projects; review their documentation to decide which fits your needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

electron-builder suits developers who ship an Electron app to users on macOS, Windows and Linux and want packaging, code signing, publishing and auto-update handled by one tool. It is not for people who are not building an Electron app, or for anyone who needs an end-user desktop application to install.

Install options & downloads