serpantinum

ilyamiroAGPL-3.0活跃维护

基于 QML 和 Quickshell 打造的 Wayland 桌面 Shell，为 Hyprland、Niri、Sway 等合成器提供统一的面板、启动器与桌面组件。

A shell for wayland compositors

v2.5.1发布于 2026-11-10 14:29 UTC7,671star +36 / 7 天358fork同步于 2026-11-10 23:33 UTC

Wayland 桌面Shell 合成器 QML Quickshell

对比 GitHub 官网 desktop-environment desktop-shell hyprland niri qml

怎么上手

由 README 提炼，执行前请确认

原文

curl -fsSL install.serpantinum.dev | bash
serpantinumd start

硬件要求按 README 说明

README 未说明硬件要求；仅支持运行 Wayland 合成器（Hyprland、Niri、Sway、Mango）的 Linux 桌面环境。

下载：源码 zip·GitHub Releases（安装包）本站不镜像安装包

项目说明

由 README 自动翻译提炼

没人工点评？写下你的经验

面向 Wayland 合成器的桌面 shell，为 Hyprland、Niri、Sway、Mango 提供统一界面与配置

基于 QML 和 Quickshell 打造的 Wayland 桌面 Shell，为 Hyprland、Niri、Sway 等合成器提供统一的面板、启动器与桌面组件。

核心能力

安装脚本自动识别发行版与当前合成器并部署配置
内置 PipeWire 音频处理器，支持均衡器、声道交换与动态 EQ
内置 Wayland 蓝光过滤守护进程，支持昼夜定时切换
支持 Hyprland、Niri、Sway、Mango 四种合成器
用 serpantinumd start 一条命令启动 shell

容易踩的坑

从 v1 迁移时旧配置会被备份并弃用，显示器、快捷键、自启动等合成器设置需自行配置；NixOS 需按官网 flake 与模块指南单独安装，不能直接用安装脚本；Fedora 上 Mango 来自 Terra 仓库、Void 上 Hyprland 来自第三方 black-hole.dev 仓库，需额外启用。

内容由模型根据 README 生成，可能不完整或不准确，以官方文档为准。看原文 README

最近发版

5 个版本v2.5.1

全部 release

v2.5.1最新正式版2026-11-10 · 2026-11-10 14:29 UTC
- fix(screenshot): silence missing qr_result FileView warning
- feat(theme): add light/dark mode switch with static preset mode detection and color-scheme sync
- fix(theme): keep matugen preset tile text and tint fixed over wallpaper, blur more
- chore(guide): remove unused theme PresetsTab stub
- feat(presets): move import preset row to the general presets tab
- feat(presets): add import preset row with file picker
- fix(network): skip bluetooth discovery when adapter is disabled
- feat(calendar): enlarge sun arc, center time labels on ends, animate sun on open
- style(calendar): soften sun arc glow
- revert(weather): restore glyph icons in bar, calendar and widgets
- feat(weather): replace glyph icons with static notification art keyed to Open-Meteo codes
- fix(surfaces): flatten corners that sit on an attached neighbour so fillets keep full radius
- fix(glass): treat fillet zones as deep interior so joins render without seams
- fix(quickactions): expose sidebar surface backdrop for glass children
- feat(popouts): use spring reveal for tray menu and side music popout
- refactor(surfaces): let attached surfaces own their joins so the bar never draws foreign shapes
- fix(bar): remove implicitHeight binding loop in left face
- fix(surfaces): cap joined fillet radius by the thinnest shape and pin dashboard content to the bar edge
- perf(surfaces): rebuild field uniforms once per frame and publish only shapes near other bands
- fix(bar): keep centered time at screen center when system panel opens
- refactor(guide): move time format setting from the time widget card to general settings
- perf(surfaces): separate band and shape revisions and skip neighbour scans for unattached surfaces
- feat(lyrics): replace no-lyrics text toggle with hide text that hides all status text
- refactor(surfaces): remove GlassFillets, corner cutout shader and dead fillet properties
- feat(glass): draw liquid glass over the surface field union and join each pair with its own fillet radius
- feat(blur): cut the blurred wallpaper by the surface field union so joins are blurred too
- feat(surfaces): draw osd, music popout and widget picker from the shared surface field
- feat(dock): draw the dock background and edge joins from the shared surface field
- feat(surfaces): draw clipboard and floating quick actions from the shared surface field
- feat(dashboard): draw the dashboard background from the shared surface field
- feat(launcher): draw the launcher background from the shared surface field
- feat(bar): draw bar outer corners and edge fillets as a union with off-screen edge shapes
- feat(tray): draw tray menus and bars from the shared surface field instead of hand-placed fillets
- feat(surfaces): add SurfaceField registry and AttachedSurface field renderer
- feat(shaders): add surface field fill and texture shaders for merged attached surfaces
- fix(lock): signal lock before sleep only after lock surfaces are shown
- feat(dashboard): attach bar-end fillets, gap in modular style and two-stage reveal when the bar is shorter than the panel
- fix(dashboard): draw fillets and flat corners only where the panel sits on the bar
- feat(calendar): scrolling curved hourly strip with current-hour focus, restyled sun arc and configured time format for sun times
- perf(launcher): speed up spring open animation for launcher and clipboard
- feat(dashboard): rework calendar into a bar-attached dashboard with spring reveal shared by launcher, clipboard and dock
- refactor(settings): manage presets through serpantinum-core instead of an embedded python script
- perf(settings): show display, widgets and presets tabs instantly on reopen
- chore: pin serpantinum-core 0.6.0
- perf(website): optimize image preloading, layout stability and animation loops
- perf(settings): load only the current page, save the search index and build heavy pages progressively
- feat(i18n): translate lock screen prompt background setting
- Merge PR #578: lock screen prompt background option
- feat(
v2.5.02026-11-09 · 2026-11-09 13:06 UTC
查看更新说明
- feat(weather): replace quiet hours selectors with a draggable time range slider in its own group
- style(weather): redraw cloud, sun, bolt, rain, wind, fog and waves and pin the warning shield position
- feat: add weather and government warning notifications with illustrated cards and a Weather settings tab
- fix(network): decode wifi security by enum so open and OWE networks skip the password prompt
- fix(media): blur album art in QML and keep the largest cover for each track
- perf: load wallpaper picker on demand, cap visualizer updates and bound paused searches
- feat: new widgets: Timer, Stopwatch, Pomodoro for desktop. Adaptation of the quickactions
- docs(readme): add subreddit invite above installation
- chore(aur): bundle Ski 0.6.3
v2.4.32026-11-08 · 2026-11-08 00:22 UTC
查看更新说明
- fix(wallpaper): wait for the frozen frame capture to finish before starting an interrupting transition
- style(wallpaper): give transition previews a 16:9 aspect ratio
- fix(wallpaper): declare tint on transition mask shaders to silence missing property warnings
- style(wallpaper): lay transition previews out in a three-column grid like the bar style cards
- feat(wallpaper): add paint transition that grows the new wallpaper in from cell colonies
- feat: quit serpantinum-core, -audio and -gamma when serpantinumd stops, and leave gamma running through installer updates
- feat(installer): restart running core and gamma daemons after updating them, with one helper shared with audio
- Revert "feat: restart serpantinum-core, -audio and -gamma daemons left running from an older install"
- feat: restart serpantinum-core, -audio and -gamma daemons left running from an older install
- feat(wallpaper): index wallpapers with serpantinum-core and drop indexer.py
- feat(network): read addresses, Wi-Fi frequency and connectivity from serpantinum-core instead of polling nmcli, ip and iw
- chore: pin serpantinum-core 0.5.0 and drop iw
- feat(visualizer): read the spectrum from serpantinum-audio instead of cava
- feat(quickactions): add floating open, close and toggle IPC
- chore(deps): drop pavucontrol, bluez-utils, and git and unzip as runtime dependencies
- fix(updater): pass notification text as arguments so the shell never expands it
- chore: pin serpantinum-core 0.4.1 and drop libnotify
- fix(i18n): suggest serpantinum-core notify in idle command examples
- refactor(notifications): send notifications with serpantinum-core notify instead of notify-send
- chore(deps): drop inotify-tools
- refactor(recording): watch the recording pid file with FileView instead of inotifywait
- refactor(quickactions): remove unused dock quick action
- chore(deps): drop unused packages and python/qt websockets
- fix(guide): keep drag chip lists consistent when shown ids are a Qt sequence or settings reload mid-drag
- feat(wallpaper): add recently applied/recently added switch to the recent tab
- style(switch): add horizontal padding so option text doesn't hug the edges
- refactor(wallpaper): use larger font icons for filter tabs and a circular arrow for recently applied
- fix(tray): keep menu fillets on the straight bar edge and fill the bar's rounded end when the menu overhangs it
- feat(tray): glide the menu between tray icons instead of jumping
- feat(tray): animate submenu open/close and slide a single panel between sibling submenus
- fix(tray): collapse redundant menu separators and pixel-align submenus to remove the seam
- fix(tray): keep attached submenus inside their parent's side and detach ones that don't fit
- fix(lock): start password auth immediately after resume and queue early enter presses (#564)
- fix(fillets): stop toggling ear visibility so the blur mask no longer randomly renders empty on reopen
- fix(launcher): offset attached launcher by the solid bar's edge margin so it no longer overlaps the bar
- refactor: list monitors with serpantinum-core monitors and remove the monitors_detect script and its cli entry
- chore: pin serpantinum-core 0.3.0
- refactor: rename the blue light filter command, script and qml singleton to gamma
- refactor: remove the unused current_focus script and its cli entry, docs and translations
- docs: group the package pages under components with one page per package
- docs: add serpantinum-gamma pages and name the docs sections after their packages
- docs: add serpantinum-core pages and link them from the sidebar and install table
v2.4.22026-11-06 · 2026-11-06 23:17 UTC
查看更新说明
- chore: pin serpantinum-core 0.2.0 and drop brightnessctl and python-jeepney dependencies
- feat: move launcher ranking, file search and the hibernate and fingerprint checks to serpantinum-core
- feat: track screen time and read wellbeing stats through serpantinum-core instead of the Python focus daemon
- feat: replace the Python idle helper with serpantinum-core watch idle
- feat: read and set brightness through serpantinum-core and drop brightness.sh
- feat: read Sway, Niri and Mango state from serpantinum-core instead of compositor CLI processes
- chore: bump serpantinum-gamma to 0.7.0
- fix: update serpantinum-core to 0.1.2 for event-driven lock detection and the Hyprland LED check
- feat: read system usage, keyboard locks and clipboard history from serpantinum-core
- feat(guide): animate search view, add section labels, faint highlights and upfront search indexing
- revert(guide): restore original settings tab spacing and row styling
- refactor(guide): tidy settings layout and sidebar, fix search ids for non-Latin titles
- fix(i18n): show the fallback string when a translation key is missing
- docs: trim marketing phrasing and padding in the README and docs
- fix(quickactions): keep calculator dropdowns inside the panel by bounding their height
- fix(guide): drop uninstalled dock apps when applying settings presets
- fix(guide): show widget rotation correctly in preset previews
- fix(guide): keep preset widget previews in their saved theme without flicker
- fix(guide): restore widgets when applying settings presets and preview them live
- feat(guide): preview settings presets with captured bar and dock
- chore(aur): bundle Ski 0.6.2
- feat(guide): add settings presets tab to save and apply full setups
- feat(reusables): add shader-animated checkbox
- chore(aur): bundle Ski 0.6.1
- fix(wallpaper): shuffle from the configured wallpaper directory
v2.4.12026-11-05 · 2026-11-05 14:13 UTC
查看更新说明
- chore: remove qylock license and credit
- fix(wallpaper): freeze the current frame when a transition is interrupted
- feat(guide): add wallpapers tab with configurable wallpaper transitions
- fix(dropdown): open upward and reverse the list when there is no room below
- fix(bar): avoid implicitWidth binding loop in menu face
- chore(aur): bundle Ski 0.6.0
- refactor(compositor): add CompositorStateBase for shared workspace index state
- refactor(reusables): add SubscriptionGate and replace hand-rolled subscription bookkeeping
- refactor(bar): add BarFaceBase and migrate bat, bt, kb, vol and wifi faces
- feat(bar): add shuffle wallpaper button to the menu module
- feat(guide): add reusable drag chip editor for menu buttons and sysmon stats
- feat(bar): add night light and caffeine toggles to the menu module
- fix(lock): mirror password input across all monitors
- fix(inputs): keep bound error state in password input
- fix(wallpaper): guard search cleanup against empty paths (#460)
- feat: add favorites tab and star toggle to the wallpaper picker
- fix: install matugen 4.x from upstream release on Fedora
- refactor: extract collapsible section and revealable row from dock tab
- refactor: extract shared usage face base components
- refactor: share screen-toggle and hover-menu logic across widget controllers
- feat: add a show distances toggle for the widget redactor and fix sentence case in widget settings
- feat: add widget distance labels, spacing and resize snapping, and arrow key nudging to the widget redactor

用户点评

登录用户的真实使用记录，可按版本和硬件筛选

共 0 条

还没有人点评。第一个说出真实体验的人最有价值。

README 原文

未翻译

在 GitHub 打开

Previews

[!IMPORTANT] Hey, join our subreddit! Share your setups, ask questions and follow updates at r/serpantinum.

Installation

[!TIP] Full installation and configuration instructions live at serpantinum.dev.

[!IMPORTANT] Migrating from v1: All previous configuration will be backed up and unused. Configuration of compositor settings such as monitors, keybinds, and autostart is now up to you, as the project migrated from being dotfiles to being a shell.

Arch Linux, Fedora, Void Linux and their derivatives

For Arch-based distributions (including systemd, OpenRC, and other init systems), for Fedora-based distributions such as Nobara and Ultramarine, and for Void Linux (glibc and musl), run the automated installation script. It detects your distribution and uses pacman, dnf or xbps.

Use this installer:

curl -fsSL install.serpantinum.dev | bash

If this doesn't work, use:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/ilyamiro/serpantinum/master/install/install.sh)"

[!NOTE] To update, run the script again and choose "update".

NixOS

See the NixOS installation guide for flake setup, the NixOS and Home Manager modules, and updating.

Audio engine

The equalizer, balance, mono, channel swap, dynamic range modes and the dynamic EQ run on serpantinum-audio, a small PipeWire processor that replaces EasyEffects. The installer and the packages install it, and on the first start after updating, Serpantinum hands your audio over from EasyEffects. See the audio engine guide.

Blue light filter

The blue light filter and its day and night schedule run on serpantinum-gamma, a small Wayland daemon that replaces wl-gammarelay-rs. The installer and the packages install it. Serpantinum starts it the first time a filter is turned on and stops it on exit.

Supported compositors

Hyprland, Niri, Sway and Mango. The installer detects the running compositor and deploys its configuration. On Fedora, Mango is installed from the Terra repository. On Void Linux, Hyprland is installed from the third-party black-hole.dev repository.

Running

To run the shell, launch serpantinumd start

For configuration, see the configuration guide.

License

This project is licensed under the GNU Affero General Public License version 3, or (at your option) any later version. See the LICENSE.md file for the full license text.