--- title: "SMBAct on Ubuntu GNOME (Wayland): install the GNOME Shell extension" description: "Set up SMBAct on Ubuntu GNOME under Wayland: install the SMBAct GNOME Shell extension in three steps, update it, and turn it back on if GNOME disables it." canonical: https://smblob.com/products/smbact/documentation/gnome-wayland/ date: 2026-11-08 locale: en --- # SMBAct on Ubuntu GNOME (Wayland): install the GNOME Shell extension > Markdown version of https://smblob.com/products/smbact/documentation/gnome-wayland/ > Same content as the HTML page without navigation, styling or scripts. Cite the HTML URL. > Site structure and the full page list for agents: https://smblob.com/llms.txt Set up SMBAct on Ubuntu GNOME under Wayland: install the SMBAct GNOME Shell extension in three steps, update it, and turn it back on if GNOME disables it. [SMBAct](https://smblob.com/products/smbact/) › [Documentation](https://smblob.com/products/smbact/documentation/) › Ubuntu GNOME (Wayland) ## SMBAct on Ubuntu GNOME (Wayland) How to enable all of SMBAct in a GNOME Wayland session — Ubuntu 25.10 and newer, including 26.04, where GNOME runs on Wayland only. It takes three clicks and one log-out. Screenshots: Ubuntu 26.04.1 with GNOME Shell 50.1, SMBAct 2.0.0 (English interface). On **KDE Plasma** nothing needs to be installed — see [SMBAct on KDE Plasma (Wayland)](https://smblob.com/products/smbact/documentation/kde-plasma-wayland/). > **Open source:** SMBAct’s GNOME Shell extension is GPL-2.0-or-later. Source code and issues on GitHub: [GigLaboCom/smbact-shell](https://github.com/GigLaboCom/smbact-shell). ## Why an extension is needed Under Wayland an application cannot see other applications’ windows and cannot catch hotkeys while another app is focused. Without help from the desktop, SMBAct sees only X11 apps (XWayland). That is why SMBAct ships a small GNOME Shell extension: with it SMBAct sees and arranges every window, and its hotkeys work whatever window is focused. SMBAct detects the session and the desktop by itself — there is nothing to configure. In an X11 session the extension is not needed. It is part of the SMBAct package, and its source code is open: [github.com/GigLaboCom/smbact-shell](https://github.com/GigLaboCom/smbact-shell). ## Install: three steps and one log-out ### 1. Click “Install” ![Banner “Install SMBAct's GNOME Shell extension” with an Install button above the SMBAct dashboard](https://smblob.com/docs/smbact/gnome-wayland/01-install-banner.webp) On first launch under GNOME Wayland the main window shows the banner “Install SMBAct’s GNOME Shell extension”, and the dashboard’s **Window engine** line says “GNOME Shell extension not installed”. Click **Install**: SMBAct installs the extension for your user and enables it for your next login. ### 2. Save your work and click “Log out…” ![Banner “Log out and back in to start SMBAct's GNOME Shell extension” with a Log out button](https://smblob.com/docs/smbact/gnome-wayland/02-log-out-banner.webp) GNOME starts new extensions only at login, so one log-out and log-in is needed. Save your work first — applications close when you log out. Then click **Log out…**. You can also skip it and log out later from the system menu: the extension starts at your next login. ### 3. Confirm in the GNOME dialog and log back in ![GNOME “Log Out” dialog with Cancel and Log Out buttons](https://smblob.com/docs/smbact/gnome-wayland/03-gnome-log-out-dialog.webp) This is the regular GNOME dialog. **Log Out** logs out immediately; if you press nothing, GNOME logs out by itself after 60 seconds. **Cancel** keeps you logged in and the banner stays. Log back in and start SMBAct if it does not start at login. ### Done ![SMBAct dashboard without the banner, Window engine: GNOME Shell extension; Text Editor in the right half of the screen](https://smblob.com/docs/smbact/gnome-wayland/04-done-dashboard.webp) The banner is gone and the **Window engine** line reads “Separate process · GNOME Shell extension” with a green dot. In the screenshot, Text Editor (a native Wayland app) was sent to the right half of the screen with `Ctrl + Super + →` while it was focused. ![SMBAct switcher with previews of xterm and SMBAct (X11) and Files, Text Editor and a Firefox dialog (Wayland)](https://smblob.com/docs/smbact/gnome-wayland/05-switcher-wayland.webp) The switcher (`Ctrl + Alt + X`) opens whatever window is focused and shows all windows with previews. Previews of Wayland windows come from the extension: they appear instantly from a cache and refresh within a fraction of a second if the window changed. X11 windows are captured live. ![SMBAct actions popup centred on the Text Editor window](https://smblob.com/docs/smbact/gnome-wayland/12-actions-popup.webp) The actions popup (`Ctrl + Alt + Z`) appears centred on the window the action will apply to. ## Updating the extension When a new SMBAct version brings a new version of the extension, SMBAct offers to update it. The old version keeps working until you log in again. ### 1. Click “Update” ![Blue banner “A newer version of SMBAct's GNOME Shell extension is available” with an Update button](https://smblob.com/docs/smbact/gnome-wayland/06-update-banner.webp) The banner names both versions: the one SMBAct brought and the one that is running. The dashboard says “GNOME Shell extension update available”. ### 2. Log back in when convenient ![Blue banner “Log out and back in to finish the extension update” with a Log out button](https://smblob.com/docs/smbact/gnome-wayland/07-update-log-out-banner.webp) The new version is already on disk. Click **Log out…** or log out later yourself: after login GNOME starts the new version and the banner disappears. Until then everything runs on the old one. ## If the extension was turned off The extension can be turned off in the Extensions app (or Extension Manager), or all extensions can be turned off at once. GNOME also turns all extensions off by itself if the session crashed within the first minute after login. SMBAct notices this immediately. ![SMBAct notification about the disabled extension and a banner with a Turn it on button; Window engine: GNOME Shell extension off](https://smblob.com/docs/smbact/gnome-wayland/08-extension-off.webp) You get one notification, and the main window shows a banner with a **Turn it on** button. While the extension is off, SMBAct works as it would without it: it sees only X11 apps, and hotkeys fire only while an X11 window is focused. The notification comes only if the extension was turned off while SMBAct was running, and it respects the **Desktop notifications** and **Play sound** settings. ![Blue banner “Turning on SMBAct's GNOME Shell extension…”](https://smblob.com/docs/smbact/gnome-wayland/09-turning-on.webp) After the click the extension is turned on right away — no new login needed. SMBAct takes a couple of seconds to switch over to it. ![SMBAct dashboard without the banner again, Window engine: GNOME Shell extension](https://smblob.com/docs/smbact/gnome-wayland/10-turned-on.webp) Everything works again. ![Banner “GNOME extensions are turned off” with a Turn on extensions button and a note that all extensions will be turned on](https://smblob.com/docs/smbact/gnome-wayland/11-all-extensions-off.webp) If all extensions are turned off, the button is called **Turn on extensions**. It turns on all your GNOME extensions, not only SMBAct’s, and the note under it says so. If the extension stopped with an error, the banner suggests logging out and back in and shows GNOME’s message. ## Good to know - On the lock screen SMBAct hotkeys do not fire: GNOME turns extensions off while the screen is locked. After unlocking SMBAct picks everything up by itself, without notifications. - If an SMBAct hotkey matches a GNOME shortcut (for example `Super + ↑`), GNOME keeps the shortcut for itself. SMBAct marks that hotkey field with a warning. - The extension is installed to `~/.local/share/gnome-shell/extensions/smbact@giglabo.com`. To remove it by hand run `gnome-extensions uninstall smbact@giglabo.com`; SMBAct then shows the “Install” banner again. - To check that the extension is running: `gnome-extensions info smbact@giglabo.com` (the line `State: ACTIVE`). ## Other platform guides - [SMBAct desktop plugins on GitHub](https://github.com/GigLaboCom/smbact-shell) — source code and issues of the GNOME Shell extension and the KWin script. - [Install SMBAct on macOS](https://smblob.com/products/smbact/documentation/install-macos/) — the dmg, the first open and the Accessibility and Screen Recording permissions. - [SMBAct on KDE Plasma (Wayland)](https://smblob.com/products/smbact/documentation/kde-plasma-wayland/) — nothing to install, and what to do about Plasma’s own shortcuts. - [Install SMBAct on Windows](https://smblob.com/products/smbact/documentation/install-windows/) — getting past the Edge download warning and SmartScreen. - [Download SMBAct](https://smblob.com/products/smbact/download/) · [Documentation](https://smblob.com/products/smbact/documentation/) · [Control windows with keyboard](https://smblob.com/products/smbact/features/control-with-keyboard/) ## Related - HTML version of this page: https://smblob.com/products/smbact/documentation/gnome-wayland/ - Site map for agents: https://smblob.com/llms.txt