Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AhmedSaadi0/NibrasShell/llms.txt

Use this file to discover all available pages before exploring further.

NibrasShell supports static images, animated GIFs, and videos as wallpapers, and can automatically rotate through a folder of images on a configurable timer. Beyond simply displaying an image, the shell adds a depth effect that composites a foreground subject over the wallpaper — creating visual separation between the desktop clock and the background. Blur is applied contextually when menus open, so the wallpaper softens behind overlaid panels without changing the base image.

​
Wallpaper types

Any common image format (PNG, JPG, WEBP) works as a static wallpaper. Set the path in the Settings App or point _wallpaper in your theme file to the full path or a bundled asset key.
// In your theme file
_wallpaper: "/home/you/wallpapers/mountain.png"
If you provide just a filename without a path separator, NibrasShell resolves it against the bundled assets folder automatically.

​
Setting your wallpaper

1

Open the Settings App

Press your configured shortcut or click the settings icon in the left sidebar to open the Settings App.
2

Go to Wallpapers

Navigate to the Wallpapers section. You will see tabs for local wallpapers, downloaded wallpapers, and Wallhaven search.
3

Choose a source

  • Local — wallpapers scanned from your ~/Pictures folder and default asset paths.
  • Downloaded — wallpapers previously downloaded from Wallhaven, stored in the NibrasShell downloads folder.
  • Wallhaven — search and download directly from the Wallhaven API without leaving the Settings App.
4

Click a wallpaper to apply it

Selecting a wallpaper applies it immediately. If dynamic coloring is enabled for your active theme, the color pipeline runs automatically after the wallpaper loads.

​
Depth effect

The depth effect adds a transparent overlay layer on top of the wallpaper. The overlay is a cutout of the wallpaper’s foreground subject (for example, a person, animal, or object) with its background removed. The desktop clock sits between the wallpaper and the overlay, so the subject appears in front of the clock — creating a convincing layered composition.

​
Generation methods

NibrasShell provides two scripts for generating depth overlays:

rembg (AI-based)

create_depth_image_rembg.py uses the rembg library with U-2-Net or ISNet models to remove the background. This produces cleaner results, especially around hair, fur, and complex edges. Requires Python and rembg to be installed.Configurable parameters:
  • model — model name (default: u2net; alternative: isnet-general-use)
  • alphaMatting — enable edge refinement (slower but higher quality)
  • foregroundThreshold, backgroundThreshold, erodeSize — matting controls

OpenCV

create_depth_image_opencv.py uses classical computer vision for background removal. It runs faster and requires no additional model downloads, but handles complex edges less accurately than the AI approach.

​
Enabling the depth effect

1

Open the Settings App

Go to Wallpapers → Depth Effect.
2

Select a generation method

Choose rembg (recommended) or OpenCV from the method selector.
3

Generate the overlay

Click Generate. NibrasShell runs DepthEffectController in the background, which calls the appropriate Python script with your current wallpaper. A progress indicator appears while generation runs.
4

The overlay is applied automatically

When the script finishes, the overlay path is saved to the theme cache as _desktopClockDepthOverlayPath and applied immediately.

​
Cache and cleanup

Generated overlay images are stored in ~/.cache/nibrasshell/themes/. The filename is a random string so multiple overlays can coexist. When you switch themes or wallpapers, old overlays may become unused. NibrasShell automatically cleans up stale overlays by running overlay_cache_images_cleaner.py, which compares the cache folder against all depthOverlayPath values referenced in theme cache files and removes any orphaned images. You can trigger cleanup manually by calling ThemeManager.cleardUnusedOverlayImages() from the Quickshell console.
Several preset themes (Dracula, Deer, Colors, Material You) ship with pre-generated depth overlays bundled as assets, so the depth effect works out of the box without running any scripts.

​
Wallpaper blur

NibrasShell applies blur to the wallpaper layer in two contexts:
When any overlay menu (the right-click menu, the app launcher, or similar panels) opens, the wallpaper blurs behind it. Enable this with _enableWallpaperBlur: true in your theme. The blur intensity is controlled by _wallpaperBlurStrength (range 0.0–1.0, default 0.9).
_enableWallpaperBlur: true
_wallpaperBlurStrength: 0.9
In non-floating sidebar modes, opening the LeftWindow (the left sidebar/menu panel) animates the desktop container sideways. The wallpaper blurs behind the panel during this transition to visually separate the panel from the desktop content.
Hyprland-level blur (configured via _hyprBlurEnabled, _hyprBlurSize, and _hyprBlurPasses) is separate from wallpaper blur. Hyprland blur affects window decorations and transparent surfaces; wallpaper blur is a QML layer effect applied to the PanelWindow background itself.

Build docs developers (and LLMs) love

Get started for freeTalk to us