Develop Electron in Docker

Thomas Peklak

Thomas Peklak



Electron and Docker


There are several reasons to develop in Docker and not on your host machine. First, when it comes to backend services, you can guarantee that your development runtime is the same as in production, which can eliminate some scenarios where inconsistencies can lead to problems in production.

Of course, this doesn't really apply to Electron because their apps are bundled up and shipped to your users — here you don't have any control over the environment. Even so, you can have build dependencies where you want to have either an easier setup for the whole development team or you want to guarantee that every developer has the same system dependencies as your build servers installed.

My case was different: my colleague had to introduce a new dependency with a native module. It worked well on his machine, but created a segfault on mine. I'm not familiar with debugging segfaults and getting my development setup up and running again was urgent. Before I turned to Docker I tried different versions of Electron and the library but always ended up with the same result: it worked on other machines but not on mine. The library even worked well using the corresponding NodeJS version there only seemed to be a problem with Electron.

As I thought that this was just a temporary issue and would be fixed in future versions of the library or Electron, I was happy to have a temporary solution.


Based on this directory structure we can build a Docker image from a Dockerfile which installs all node modules, performs an electron rebuild, and does some other black magic.

Directory Structure

  • package.json
  • package-lock.json
  • Dockerfile
  • src
    • main.js
    • index.html

It's important that your files are not located in the root folder because we want to mount the source directory into the container, so we can continuously work without rebuilding the image. We only need to rebuild the image if there is a change in the npm dependencies.

# use the version that corresponds to your electron version
FROM node:14.16

# install electron dependencies or more if your library has other dependencies
RUN apt-get update && apt-get install \
    git libx11-xcb1 libxcb-dri3-0 libxtst6 libnss3 libatk-bridge2.0-0 libgtk-3-0 libxss1 libasound2 \
    -yq --no-install-suggests --no-install-recommends \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

# copy the source into /app
COPY . .
RUN chown -R node /app

# install node modules and perform an electron rebuild
USER node
RUN npm install
RUN npx electron-rebuild

# Electron needs root for sand boxing
# see
USER root
RUN chown root /app/node_modules/electron/dist/chrome-sandbox
RUN chmod 4755 /app/node_modules/electron/dist/chrome-sandbox

# Electron doesn't like to run as root
USER node
CMD bash

Now, we can build the Docker image and start a container. If you have other files and folders in your root directory, you need to mount each single one separately. You can't mount the root directory as this will also overwrite the node modules.

docker build -t electron-wrapper .
docker run -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=unix$DISPLAY -v`pwd`/src:/app/src --rm -it electron-wrapper bash

This should fire up a bash prompt from which you can start your development workflow, e.g. npm start.

Example package.json

    "name": "electron-in-docker",
    "version": "1.0.0",
    "description": "",
    "main": "src/main.js",
    "scripts": {
        "start": "electron . --no-sandbox"
    "author": "",
    "license": "ISC",
    "devDependencies": {
        "electron": "^13.1.7",
        "electron-rebuild": "^2.3.5",
        "libxmljs": "^0.19.7"


This guide works in Linux and likely in WSL2. For macOS, you can take a look at Jake Donham's blog post in the links below, which helped me a lot to get started. I always find it good to have some backup in my developer's toolbox if things break in unpredictable ways. Running programs in Docker is one of my all-time favorites.

Further reading


Example repository

If you want to try it out yourself, you can take a look at the electron in docker repository.

Your opinion is very important to us!

On a score of 1 to 5, what's your overall experience of our blog?
1...Very unsatisfied - 5...Very Satisfied

More insights

5 steps you should consider before building software

Thinking about developing your own software? Here are 5 steps you should definitely consider before you start.

software development, digital buiness, discovery

Read full story

Why new software needs change management & how to plan it

Implementing a new software solution means change at every level of your business — here's where a solid change management plan comes in.

software development, digital buiness

Read full story

4 alternatives to Excel sheets for a smooth business workflow

Locked out of an Excel spreadsheet? Here are 4 alternatives to Excel to better suit your unique business needs & scale.

software development, digital buiness

Read full story

UX Case Study: Bulk Upload

A bulk upload function describes a product feature that allows the user to upload several different files at the same time and correctly process them.

software development, ux, ui

Read full story

UX vs. UI Design

Have you ever heard someone use the terms UX and UI in a discussion? These are not abbreviations for fantasy worlds or anything like that, UX and UI are among the most important components of product development.

software development, ux, ui

Read full story

The meaning of a thorough discovery phase to optimize software development

Planning software projects or new digital applications is challenging, and sometimes the initial plan does not work out. Often, the reason for failure is a missing or insufficient product discovery phase.

software development, discovery phase

Read full story

See how custom business software has helped our clients succeed, no sales pitch involved. Just real-world examples. Guaranteed.

Schedule a demo