A Comprehensive Guide on GNOME Shell Extensions

The GNOME shell extension is designed with an objective of empowering the elements of a GNOME interface. It may either work for window management or while someone is launching an application. The shell works for loading numerous JavaScript and CSS. This offers developers an opportunity to make changes and share changes with our professionals. In fact, the features eliminate the need for patching the original source code and recompile it once again.

The extension system serves to be a substitute for the system related to ‘widgets’ and ‘applets’. While the panel can be appended or customized with a set of items, individuals can take the benefit of doing more. For instance, the developer can add a custom search provider when the need arises.

How to Create an Extension?

Step 1: Once you are familiar with the GNOME shell’s developer console, you should open the tab with the list of installed extensions.

Step 2: In case there’s an error, then it would appear in the ‘Errors’ tab.

Step 3: You can create the shell extension from an interactive creator that runs smoothly on the Unix terminal. As an example, you can view the script as shown below.

gnome-shell-extension-tool –create-extension

As far as the structure is concerned, a developer should specify the uuid that nothing but a dummy email address and not the actual one which you have been using currently. Moving ahead, the directory comprises of metadata.json and extension.js. The former would appear something like a code as below.


“uuid”: “”,

“name”: “My Cool Extension”,

“description”: “Make windows burst into flame”,

“url”: “”,

“shell-version”: [ “3.2.2” ]


But, when you consider extension.js, the function ‘init’ would be called once the Javascript file is loaded. You must change the interfaces in the ‘enable’ function and remove functionalities in the ‘disable’ function.

So, typically, the extension would be as follows





NOTE: It’s optional to include the ‘stylesheet.css’ within the directory. Depending on your requirements, you may or may not add the .css file.

How to Write an Extension?

Consider creating an extension by the name, ‘helloworld’ with the UUID as and description being GNOME 3 Shell extension. The tool which is the Python script would create a subdirectory under ~/.local/share/gnome-shell/extensions and include it with three files. So, the files would look something as mentioned below


$ cat metadata.json


“shell-version”: [“2.91.92”],

“uuid”: “”,

“name”: “helloworld”,

“description”: “My first GNOME 3 Shell extension”



$ cat extension.js


// Sample extension code, makes clicking on the panel show a message


const St =;

const Mainloop = imports.mainloop;

const Main = imports.ui.main;


function _showHello() {

let text = new St.Label({ style_class: ‘helloworld-label’, text: “Hello, world!” });

let monitor = global.get_primary_monitor();


text.set_position(Math.floor (monitor.width / 2 – text.width / 2),

Math.floor(monitor.height / 2 – text.height / 2));

Mainloop.timeout_add(3000, function () { text.destroy(); });



// Put your extension initialization code here

function main() { = true;‘button-release-event’, _showHello);



$ cat stylesheet.css

/* Example stylesheet */

.helloworld-label {

font-size: 36px;

font-weight: bold;

color: #ffffff;

background-color: rgba(10,10,10,0.7);

border-radius: 5px;


After the compiling the code, you would see ‘Hello, world!’ projected on the desktop.

How to Install GNOME Shell Extensions?

 For installing the extensions, you need to navigate to the Gnome-shell extensions web page /

Step 1: As you click the extension, you would be redirected to a page where you need to mention a short description.

How to install GNOME shell extensions

Step 2: On the web page, you need to turn on the switch if you have decided to proceed with the installation. As soon as the prompt pops up on the screen, you must click ‘Install’.


Finally, the link: makes it easier to manage the installed extensions. Once you go to the ‘installed extensions’ tab, you can disable settings or upgrade the extensions at any point of time.

How to Update an Extension?

Once you see the list of extensions, you can update the extension with the option shown below.

Later, as you click on the gear-like option, you would be prompted for seeking the permission of installing a new extension. You then have to click the ‘Install’ button and wait for a few minutes as the update gets loaded.

How to update an extension

How to Enable Extensions?

Extensions can be disabled or enabled as you visit In case of systemwide extensions, you need to turn them on before using them. You can take help of a GNOME tweak tool or perform the task with the GSettings key which is For experiencing the effects of the code, the GNOME shell has to be reloaded with Alt+F2 followed by pressing the ‘r’.

How to Debug Extensions?

 If you are using a systemd-based systems, the log output can be seen through journalctl /usr/bin/gnome-shell –f. But, for other systems, the logs might be written in ~/.xsession-errors.

Best GNOME Extensions

Once you go through the website which is updated with a repository, you can discover a collection of extensions. In case you have the recent version, then you need to flip the switch that’s present on the extension page. If you face any issues, then you can click on the link towards the bottom of the web page and report the bug instantly. So, here’s a list of the best extensions you can always explore.

Dash to Dock

You would surely compliment Dash to Dock once you start using it. The extension aids in shifting the dash out from the overview and transform it into a dock. Eventually, it would be a breeze for launching applications and toggling between several windows and desktops. As for the placement, you can either place the dock at the bottom or along one of the sides of the computer screen.

Dash to Dock


If you wish to know the climatic conditions, then OpenWeather shows the forecast on the desktop by capturing data from / The appearance can always be customized as settings appear on the panel.

Activities Configurator

If you’re thinking about a different look for the Activities button and the panel, then you can achieve the task through Activities Configurator. Once you click on an icon, you can launch the Gnome Shell Extension Preferences Tool. Best of all, you get more from the desktop with a set of 20 different options.

Activities Configurator


When you are not working with the computer, then Caffeine prevents the PC to go into the sleep mode. Once you disable the screensaver you can select ‘auto suspend’.


Music Integration

Once you are with the GNOME shell extension, you can bring the soundtrack on the bar. As you open the audio file, it automatically gets added to the list. Later, you won’t have to navigate folders but play the file by clicking on the extension icon.

Hope you have a wonderful time playing around with GNOME shell extensions. Do share the blog with your companions in case you find it useful.


Written by Hardip Koradia

Hardip Koradia is a pro tech blogger with years of experience in writing resourceful articles on different tech topics like mobile apps, PCs, gadgets, software, how to guides, etc. His passion for technology inspired him to start Techbylws, a growing tech blog.