I have found the source code of gnome-shell UI js files on the Debian website:


Then I have also found this answer here, which points out that this path/file existed in Ubuntu some time ago:


Now however, I don't see a js subdirectory in /usr/share/gnome-shell/.

I have searched the entire / partition for "lightbox.js" and "windowManager.js", but none were found.

Where can I find these files, and what hurdles do I need to overcome if I want to change the value of some hardcoded variables in there?

2 Answers 2


Answer compat:
Ubuntu 20.04.2
gnome-shell version: 3.36.4
display server: X.Org Server

Important note:

Making any mistake while altering gnome-shell's files can introduce a deadlock of your graphical session. Attempt it only if you are familiar with common methods of system recovery.

Also, executing changes in this answer will demand an additional workflow to handle gnome-shell updates with due caution, as explained below.

Modifying functionality

On Ubuntu 20.04, gnome-shell's javascript files are normally packaged up inside the file:


To override them, one needs to extract copies of the subject files, and ask Gnome to use the copies.

Below I provide an abstracted, task-agnostic walk-around. To see a similar procedure in action on a specific practical task, see this answer.

The to-be-modified file copies can be organized in an arbitrary location, in this walk-around I use the following location:


(I chose this obnoxious directory name on purpose, for security considerations. You, following this guidance, hopefully will use a less obnoxious directory name which will be unique to your system. More details on this a little more below.)

To enable this "customization platform", one needs to place the following line in ~/.profile:

export G_RESOURCE_OVERLAYS="/org/gnome/shell=$HOME/.this-custom-thing"

For this to take effect, logging out and logging back in is necessary.

A note on dependencies:

Before I got this procedure working on my machine, I already had the libgtk-3-dev package installed. It's for development / debugging, just like the resource overlays feature seems to be so. Therefore right now I cannot determine whether respecting the G_RESOURCE_OVERLAYS environment variable depends on the presence of this package or not... Just in case, be ready to install it.

Setting up subject files:

One can list the contents of libgnome-shell.so as follows:

gresource list /usr/lib/gnome-shell/libgnome-shell.so

The next step is extracting the to-be-modified file. Let's use an example where this file is located in gnome-shell's ui/ subdirectory.

mkdir ~/.this-custom-thing/ui

gresource extract /usr/lib/gnome-shell/libgnome-shell.so \
/org/gnome/shell/ui/fileName.js > ~/.this-custom-thing/ui/fileName.js


To see the effect of tweaks on the customized file, reloading the gnome-shell after each edit seems to be necessary. It can be done quickly by issuing the r command through the Run command dialog (revealed by Alt+F2).

At this point you should have a working override which persists through reboots.

A note on recovery:

If a modification attempt goes wrong, it should be possible to switch to a virtual console environment (with e.g. Ctrl+Alt+F3). From there, commenting out the G_RESOURCE_OVERLAYS line in ~/.profile and subsequently rebooting should disengage the override and thus have the capacity to restore the system.


These javascript files are executable files that may get executed with privileges matching gnome-shell's.

However, while these files sit in the user's home directory they are subject to be altered with mere privileges matching the user's.

That may be a security concern.

Accordingly, I highly recommend that after the tweaking of functionality is succesfully completed,

  • these modified files are moved somewhere to the system root (inside /), and
  • their reference in ~/.profile (the final value in the line starting with export G_RESOURCE_OVERLAYS="/org/gnome/shell=) is updated to reflect their new location within /.
    • There they will enjoy the standard Linux policy that they can be altered only with root privileges.


It may be the case that this feature is aimed primarily at debugging and development, and perhaps not for permanent usage.

The system's stability may be impacted: when I first enabled this, I saw some previously not experienced weirdness with my sound settings, and some window-flickering. A few restarts of the gnome-shell and a (few?) reboot(s?) however solved it, and from the next day on I haven't experienced any further anomalies.

Furthermore, in the "Logs" app I can see that the event of using G_RESOURCE_OVERLAYS gets logged in the "security" section, so that's good to consider.

Regarding receiving system updates while using G_RESOURCE_OVERLAYS:

The following section is entirely speculation, I have no confirmation about whether any of this is valid; yet it may be useful to consider:

If and when gnome-shell receives an update, I see a chance that the customized gnome-shell files might lose their compatibility, and may even cause the desktop to break.

I believe in such case one could suspend using the G_RESOURCE_OVERLAYS feature through ~/.profile (as discussed in the recovery section), subsequently repeat extracting the subject files from the fresh libgnome-shell.so, and re-apply the modifications in a compatible manner.

In case an update causes such an event of incompatibility, I speculate some risk involving the desktop crashing already while the configuration stage of the updates are being executed; I can vision significant collateral damage inflicted on other systems in such a case. (I might be wrong.)

Nevertheless, for this reason, I would consider to let gnome-shell updates to be installed separate from other updates, so that the event could not interfere with the installation of other packages.

A layer of control, for stability:

To manage the aforementioned risks, one can put gnome-shell on hold status, that prevents its updates from installing, until one is ready to deal with them.

The procedure then looks like this:

  • hold gnome-shell: sudo apt-mark hold gnome-shell
  • live life in peace for however long
  • when gnome-shell has available updates, it will show up in the updates dialog, but its checkbox will be unchecked, therefore will not be installed
    • one should be able to go on like this until one is ready to perform the update
    • when ready to update, follow according to the next steps
  • run the updater, and let every update install, apart from gnome-shell's
    • reboot if necessary, and run the updater again, just to ensure that no other updates are available at the moment, apart from gnome-shell's
  • disable G_RESOURCE_OVERLAYS in ~/.profile, and restart gnome-shell
    • confirm that G_RESOURCE_OVERLAYS are indeed not used, by verifying the lack of UI customizations
  • unhold gnome-shell: sudo apt-mark unhold gnome-shell
  • run the updater and let gnome-shell update this time
  • re-enable G_RESOURCE_OVERLAYS in ~/.profile and restart gnome-shell
    • deal with any fallout of incompatibility, if necessary
      • this might involve disabling G_RESOURCE_OVERLAYS again (from a virtual console, if necessary), and re-establishing the overridden files with renewed, this time compatible modifications in them
  • having achieved a stable state again, put gnome-shell back on hold again
    • repeat the above procedure when new updates arrive

Compiling the modified files back into libgnome-shell.so

I reckon the risks around the updates can be avoided if one, instead of relying on the resource overlays feature permanently, compiles the modified files back into libgnome-shell.so (because then an update does not cause an event of incompatibility; instead it just rewrites libgnome-shell.so in one go).

However, unfortunately, this task seems to depend on a significant amount of Gnome- and/or Ubuntu-developer know-how; mere agility around code-editors does not seem to cut it.

The compiler, glib-compile-resources, requires an XML-formatted list of the resources to be compiled, and its output cannot be easily reattached to an existing .so ELF file.


At a guess, you are missing the C code used by the lower-level parts of gnome-shell, which goes into the same library as the JavaScript resources.

If you obtained gnome-shell by compiling it from source code (for instance in jhbuild) [...]

If you obtained gnome-shell from a distribution like Debian, Ubuntu [...], you will need to apply your JavaScript changes as local changes to that distribution's gnome-shell package, rebuild the gnome-shell package with a local change to the version number, and install the new package.


Compiling the entirety of gnome-shell from source is no small feature. Actually it has such an extensive impact, apparently with so many things that could go wrong with it, that I personally feel it puts the reasonability of the choice in question.

Nevertheless, if you can share the actual steps of compiling gnome-shell in the context of Ubuntu successfully, please submit an answer.

References / literature:

  • This is a very helpful answer although I do hate how difficult they make it to edit and override the code. I followed your steps to fix a bug because I cannot upgrade Gnome to a newer version in this environment and I still do not even know whether the override works at all.
    – DaVince
    May 31, 2021 at 18:58
  • 1
    Great help! I did not need libgtk-3-dev on Ubuntu 22.04. Btw, Alt+F2 -> r does not work in Wayland, default on Ubuntu 22.04.
    – Aelian
    Dec 31, 2022 at 8:35

I wanted to share an alternative approach that I found.

I could not make it work well, and it makes the system behave extra weird.

I share it only for those who feel well-skilled and experienced to try and build on it, until it becomes an actually usable alternative.

In the meanwhile, the usable answer remains my other answer to this post.

Sources for the following method:

This approach extracts all of gnome-shell's javascript files — as opposed to extracting only specific files for the purpose of altering — and arranges them in an elaborate directory layout, according to their original arrangement defined in the libgnome-shell.so binary.

Updated script for gnome-shell 3.36, that actually runs on Ubuntu 20.04:

#! /bin/bash

# Extracts contents of libgnome-shell.so
# Compatible with gnome-shell v 3.36
# https://gitlab.gnome.org/GNOME/gnome-shell/-/tree/gnome-3-36/js


echo '--> Creating custom shell directory'
mkdir $HOME/.gnome-shell-custom

cd $HOME/.gnome-shell-custom

echo '--> Preparing custom shell internal directory layout'
mkdir -p \
dbusServices/extensions/css \
dbusServices/extensions/ui \
dbusServices/notifications \
gdm \
misc \
perf \
portalHelper \
ui/components \

echo '--> Extracting resources'
for r in `gresource list $gs`; do
    echo $r
    gresource extract $gs $r > ${r#\/org\/gnome\/shell/}

Having run the above script, the following commands can enable it:

# Either
GNOME_SHELL_JS=$HOME/.gnome-shell-custom gnome-shell

# Or
GNOME_SHELL_JS=$HOME/.gnome-shell-custom gnome-shell --replace

This line can be executed in a terminal, or can be appended to the end of ~/.profile, as is.

According to my observations, when placed in ~/.profile, both lines, with or without the --replace option seem to work with a similar effect.

The result:

This results in a factory-default gnome shell,

  • that uses the Adwaita theme (with blue primary color, instead of the Ubuntu orange),
  • that uses the Yaru icon set,
  • in which fonts are weird,
  • in which all extensions are disabled (and probably not found),
  • in which one's custom gnome-shell theme does not take effect,
  • in which the dock appears only together with the activities overview, accessed by Left Super,
  • in which Ctrl+Alt+t does not open a terminal,
  • in which the logout and shutdown controls in the panel's top right corner are present, but do not have any effect upon clicking them (!)

After I have removed the GNOME_SHELL_JS line from ~/.profile, I had to reboot through the terminal, issuing sudo reboot now.

After returning to the system-default Ubuntu-installed original gnome-shell, I found that all extensions were still disabled; I had to re-enable them one by one — at least their preferences were still stored, they did not get lost.


I can imagine one could re-introduce all the Ubuntu-specific customizations and configuration on top of this factory-default gnome-shell instance.

If you know what are the necessary steps to achieve that, please post an answer.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .