# blur-my-shell: a GNOME extension that made you choose between pretty and fast

> The extension adds blur to the panel, dash, overview and application windows, and the interesting part is the two competing ways it does that. One samples the wallpaper once, stacks a pipeline of effects on it, and can be reconfigured. The other blurs live, cheap to configure, expensive to run, and defective at the edges.

**aunetx/blur-my-shell** — Extension that adds a blur look to different parts of the GNOME Shell, including the top panel, dash and overview

- Repository: https://github.com/aunetx/blur-my-shell
- Website: https://extensions.gnome.org/extension/3193/blur-my-shell/
- Stars: 2,230 · Forks: 167
- Language: JavaScript
- License: GPL-3.0
- Published: 2026-09-30 · Updated: 2026-09-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/aunetx-blur-my-shell

## The whole extension is one argument about two ways to blur

Blur is the feature, and the reason this extension is interesting is that it forces a choice the operating system usually hides. There are two ways to make a surface look frosted, and they are genuinely different operations. The first samples your wallpaper once, keeps that image, and re-applies a chain of effects to it whenever the surface is drawn. The second makes the surface translucent and blurs whatever is actually behind it at run time. The readme is unusually honest that the second is not efficient, that even though it should not bring a machine to a halt, the sampled method is preferred where possible. That single preference organises the entire extension. It explains why some components, the overview and the lock screen, use the sampled method only. It explains why others, the application folders background and the window list, use the live method only. And it explains why the ones that offer both, the panel, the dock and the popups, let you choose. When you are configuring this, you are not choosing a look, you are choosing a performance profile per surface, and the documentation is structured so that the choice is explicit rather than hidden in a default.

## A pipeline of effects you can reorder, where the order is a trap

The sampled method is configured as a pipeline, and the readme devotes real estate to how the pipeline works. You can create, duplicate, rename and delete pipelines in the first settings tab. Each pipeline is a list of effects, and you can add, configure, reorder and remove them. The effects listed include gaussian blur, Monte Carlo blur, pixelization and corner rounding, with more planned and a standing invitation to open issues for specific ones. Then comes the rule that will cost you an hour if you miss it: the order matters, because the first effect in the list is applied first. The readme spells out the consequence for the most common case. If you want to add rounded corners to a pipeline used for the panel or the dock, you have to add that effect last. Add it first and the corner mask is applied before the blur, so the blur runs over the edges you just rounded and the result is not rounded corners. That is a genuinely good piece of interface design, in the sense that the constraint is real and the documentation says so plainly, and a genuinely bad one in the sense that a drag-and-drop list with no preview of the output makes the rule easy to get wrong. There is also a guarantee that the default pipeline cannot be deleted, and a documented fallback: if you delete a pipeline that something is using, the system switches to that default. So the worst outcome of a misconfiguration is a visual change, not a broken desktop.

## Live blur is cheap to configure and the readme says its implementation is defective

The live method is simpler in the settings and carries the caveats. It only offers a gaussian blur, so there is no pipeline and no effect ordering to reason about, and you can configure the blur itself to taste. The readme calls this method not very efficient, and recommends the sampled method where possible. Then it says something more specific and more useful: the gaussian blur being used has implementation defects, and the sentence about what those defects are runs past the end of the visible text. That is the most honest thing in the readme, because it tells you the default you get on the live path is known to be imperfect rather than implying the extension has solved the problem. There is a second structural limitation, and it is a dependency rather than a defect. Rounded corners on the live method currently require a separate GNOME compatibility library, installed by following a guide in the repository, and the readme says native shell support will be picked up automatically once it is available. So on the live path, corner rounding is a workaround for a shell that does not yet do it, which means it is a moving target, and the extension is candid that it will change without your configuration changing. Round your corners on the sampled method instead, where the effect is just the last item in a list, unless you specifically need live blur on that surface.

## Whitelist or blacklist, and a monitor caveat in bold

Application window blur is where this extension stops being cosmetic and starts making decisions about your machine, and the readme is direct about the trade-offs. The sampled method for windows is described as similar to a well-known desktop system's mica effect, where the blur is a background layer and content sits on top of it. The live method is described as similar to that system's acrylic effect, showing other windows behind the application, and the readme notes the live method is more comprehensively tested and less likely to cause problems. That is a useful inversion of the general guidance, because for the shell components the sampled method is the efficient one, and for windows the readme is telling you the live one is the safer one. You also control the opacity of the window above the blur, and the readme explains both directions of that choice honestly: lower opacity is less legible, and a fully opaque setting is a way to get a blurred background with a transparent theme without touching content legibility. You can additionally make the focused window fully opaque, so the one you are working in is always readable while the background stays blurred. Then the decision that matters: two modes, a whitelist where only selected windows are blurred, which is the default, and a blacklist where everything is blurred except the selection. And finally the caveat the readme bolds, that with multiple monitors the blur may not be handled properly, plus a note that one alternative window manager may cause unexpected behaviour. Test the multi-monitor case yourself before you commit to it.

## The build packs eleven source directories and the translation target is a find and xgettext

The makefile is short and it tells you how a desktop extension is actually built and tested. A build target cleans, makes a directory, and calls the shell's own extension packer with a long list of extra sources: the metadata file, the licence, the icon resources, the interface definitions, and then six source subdirectories covering components, conveniences, effects, preferences, D-Bus integration and styles. It also passes the translation directory and a compiled settings schema, and writes a zip to a build directory. So the extension is not one script, it is a shell process with a preferences UI, a D-Bus surface, a GSettings schema and compiled translations, and the packer invocation is the contract that ties them together. The install target installs that zip, and a remove target deletes the installed directory. The test targets are the part worth noting, because they are how you develop this without breaking your session. There is a nested-shell target that launches a whole nested compositor with a slow-down factor and a dummy monitor at a fixed resolution, which is the standard way to test a shell extension without touching the session you are using. There is a preferences target that opens the preferences UI. The translation target is a find piped into the standard gettext extractor, with a rotation that regenerates every catalogue from the template on each run. It is unglamorous and it is why the extension has translations.

## Version numbers track the shell, and a compatibility library smooths one gap

The release history explains the version scheme. The three most recent tags are numbered 73, 72 and 71, with the newest published on the same day as the last commit. A GNOME shell extension that is at version 73 is not at version 73 of a library API, it is at version 73 of itself, and the reason it moves so fast is that the thing it extends is versioned hard and breaking. The readme is explicit about the dependencies this creates, and every one of them is a shell extension rather than a library. The panel blur is compatible with a panel-replacing extension and with an extension that hides the top bar, which is an admission that the shell's top bar can be replaced or hidden by other people and that your blur has to survive both. The dash blur targets the dash-to-dock extension, the application folder styling interacts with a desktop cube extension in the overview, and the window list blur targets the window list extension. So the practical model is a stack of extensions, each by a different author, each versioned against the same moving shell, and this one is the one that has to degrade gracefully. The rounded blur compatibility library is the author's answer to that, and the readme tells you to install it from a guide in the repository. If you are stacking this with three other extensions, the thing to test is not whether the blur looks right but whether your session survives the combination.

## Conclusion

Adopt blur-my-shell if you want the frosted-glass look across the shell and you are willing to pick the cheap method where the expensive one would hurt, because the extension is candid that live blur is not efficient and prefers the sampled-wallpaper method wherever it can. Do not adopt it expecting the two methods to be interchangeable, because rounded corners on live blur still depend on a separate compatibility library, static blur re-runs its pipeline on every use of the overview, and the multi-monitor caveat is stated in bold in the readme. Two things to check before you install. Read the effect-order rule, because the first effect in a pipeline is applied first, so corner rounding has to be added last or it is applied under everything else. And decide which components need live blur before you start, because some of them, the application folders background and the window list, use it exclusively and give you no static alternative to fall back to.

## FAQ

### What is the difference between static and dynamic blur in blur-my-shell?

Static blur uses a static image of the wallpaper and applies a chain of effects from a pipeline to it. Dynamic blur makes the component translucent and blurs what is behind it directly, using only a gaussian blur. The readme says dynamic blur is not very efficient and that static blur is preferred where possible.

### How do effect pipelines work in blur-my-shell?

Each pipeline is an ordered list of effects including gaussian blur, Monte Carlo blur, pixelization and corners, which you can add, configure, reorder and delete. The order matters because the first effect is applied first, so corner rounding has to be added last or the blur is applied over it.

### Which blur-my-shell components use dynamic blur only?

The application folders background and the window list extension use dynamic blur only, so there is no static alternative for those surfaces. The overview, the lock screen and the screenshot window selector use static blur only, while the panel, the dock, the popups and application windows let you choose between the two.

### Are there any known issues with blur-my-shell?

The readme notes that with multiple monitors the blur may not be handled properly, that one alternative window manager may cause unexpected behaviour, that rounded corners on dynamic blur need a separate compatibility library, and that the static method re-applies its pipeline on every overview use, which can be slow with non-native or high-iteration blurs.

### How do I build blur-my-shell from source?

The makefile build target cleans, creates a build directory, and runs the shell extension packer over the metadata, licence, icons, interface files and six source subdirectories, passing the translation directory and the compiled settings schema, producing a zip in the build directory that the install target then installs.

## Sources

- [aunetx/blur-my-shell on GitHub](https://github.com/aunetx/blur-my-shell)
- [License: GPL-3.0](https://github.com/aunetx/blur-my-shell/blob/master/LICENSE)
- [Project website](https://extensions.gnome.org/extension/3193/blur-my-shell/)
- [README](https://github.com/aunetx/blur-my-shell/blob/master/README.md)
- [Releases](https://github.com/aunetx/blur-my-shell/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aunetx-blur-my-shell