Build Instructions (macOS)

Follow the guidelines below for building Electron itself on macOS, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.

Prerequisites

  • macOS >= 11.6.0
  • Xcode. The exact version needed depends on what branch you are building, but the latest version of Xcode is generally a good bet for building main.
  • node.js (external)
  • Python >= 3.7

Arm64-specific prerequisites

  • Rosetta 2
    • We recommend installing Rosetta if using dependencies that need to cross-compile on x64 and arm64 machines. Rosetta can be installed by using the softwareupdate command line tool.
    • $ softwareupdate --install-rosetta

Building Electron

See Build Instructions: GN.

Troubleshooting

Xcode “incompatible architecture” errors (MacOS arm64-specific)

If both Xcode and Xcode command line tools are installed ($ xcode -select --install, or directly download the correct version here), but the stack trace says otherwise like so:

  1. xcrun: error: unable to load libxcrun
  2. (dlopen(/Users/<user>/.electron_build_tools/third_party/Xcode/Xcode.app/Contents/Developer/usr/lib/libxcrun.dylib (http://xcode.app/Contents/Developer/usr/lib/libxcrun.dylib), 0x0005):
  3.  tried: '/Users/<user>/.electron_build_tools/third_party/Xcode/Xcode.app/Contents/Developer/usr/lib/libxcrun.dylib (http://xcode.app/Contents/Developer/usr/lib/libxcrun.dylib)'
  4.  (mach-o file, but is an incompatible architecture (have (x86_64), need (arm64e))), '/Users/<user>/.electron_build_tools/third_party/Xcode/Xcode-11.1.0.app/Contents/Developer/usr/lib/libxcrun.dylib (http://xcode-11.1.0.app/Contents/Developer/usr/lib/libxcrun.dylib)' (mach-o file, but is an incompatible architecture (have (x86_64), need (arm64e)))).`

If you are on arm64 architecture, the build script may be pointing to the wrong Xcode version (11.x.y doesn’t support arm64). Navigate to /Users/<user>/.electron_build_tools/third_party/Xcode/ and rename Xcode-13.3.0.app to Xcode.app to ensure the right Xcode version is used.

Certificates fail to verify

installing certifi will fix the following error:

  1. ________ running 'python3 src/tools/clang/scripts/update.py' in '/Users/<user>/electron'
  2. Downloading https://commondatastorage.googleapis.com/chromium-browser-clang/Mac_arm64/clang-llvmorg-15-init-15652-g89a99ec9-1.tgz
  3. <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:997)>
  4. Retrying in 5 s ...
  5. Downloading https://commondatastorage.googleapis.com/chromium-browser-clang/Mac_arm64/clang-llvmorg-15-init-15652-g89a99ec9-1.tgz
  6. <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:997)>
  7. Retrying in 10 s ...
  8. Downloading https://commondatastorage.googleapis.com/chromium-browser-clang/Mac_arm64/clang-llvmorg-15-init-15652-g89a99ec9-1.tgz
  9. <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:997)>
  10. Retrying in 20 s ...

This issue has to do with Python 3.6 using its own copy of OpenSSL in lieu of the deprecated Apple-supplied OpenSSL libraries. certifi adds a curated bundle of default root certificates. This issue is documented in the Electron repo here. Further information about this issue can be found here and here.