Develop Electron in Docker

Thomas Peklak

Thomas Peklak

  • #docker
  • #electron
3 min read
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.

Share this insight on

More insights

7 common pitfalls you should avoid when shifting to remote work

Making the shift to remote is no easy task — here are the 7 common pitfalls we've encountered and how you can avoid them.

Why open source is good, and you should be doubling down on it

Open source software development is what we're all about — because it's what gets both our clients and us the best results and ensures they never have to rely on us. Read the complete insight here.

Inside Kafka Topics & Partitions

Read this insight to dig deeper into Apache Kafka topics & partitions, what they really are and how you can go about implementing them.

Manual data entry and processing — why you need to minimize it

Is your team still caught up with manual data entry? Are you frustrated because your software systems aren’t talking to each other? Time to automate data entry.

Why No-Code/Low-Code will change custom software development forever — and how you can benefit from it

We are in the midst of a No-Code/Low-Code boom. It’s everywhere, and everyone in tech is talking about it. Read this insight to explore what it is and how you can benefit from it.

The importance of data accuracy

Data is one of the most important topics people are talking about in business right now — but why is it important? And why is it not just about gathering any type of data? Find out here.

Ready to connect your systems?