XZram

Cross-distro Linux swap management: zram, swap files, partitions, and sysctl tuning.

XZram is a CLI-first tool for creating, removing, and customizing swap on systemd-based Linux distributions. It includes a Qt6 GUI and system D-Bus daemon (xzramd).

Features

• Read-only diagnostics — status, detect, and doctor without root
• Staged apply — write commands stage to /var/lib/xzram/pending.json; apply executes atomically
• ZRAM management — configure via systemd-zram-generator; migrate from legacy zram-tools
• Swap file management — create, resize, remove disk-backed swap (btrfs nodatacow enforced)
• Swap partitions — swap list merges active swaps and fstab partitions
• Sysctl tuning — swappiness, watermark, and page-cluster settings
• Polkit integration — granular privileged operations (no blanket sudo)
• D-Bus daemon — xzramd on io.github.XZram1 for --dbus / other clients; D-Bus activation starts it on demand (native GUI does not auto-start or require it)
• Qt6 GUI — dashboard, zram, swap files, sysctl, doctor, snapshots, and settings (CLI/pkexec-first; daemon optional)
• Configuration snapshots — automatic backups before every apply; versioned restore (app_open is manual)

Supported distros

Family	Detection / runtime	Packaging in this repo
Fedora / RHEL / CentOS Stream	Full	packaging/xzram.spec
Debian / Ubuntu / derivatives	Full	debian/
Arch / CachyOS / Manjaro	Full	packaging/aur/ (AUR) · PKGBUILD (local)
openSUSE	Full	Packaging TBD (detection supported)
Gentoo	Partial	—
NixOS / Alpine / non-systemd	Out of scope v1	—

Published distro packages are not assumed until an AUR/release is cut; use From source or the in-tree packaging files (packaging/aur/, debian/, packaging/xzram.spec) when building locally.

The release version is recorded in VERSION and CHANGELOG.md. Keep packaging (PKGBUILD, packaging/xzram.spec, debian/changelog, AppStream) and gui/CMakeLists.txt in sync — make version-check verifies this.

Prerequisites

• CLI / daemon: Rust ≥ 1.87, Cargo, Linux with systemd
• Full install / GUI: cmake, Qt6 Widgets
  • Arch: qt6-base, cmake
  • Debian/Ubuntu: qt6-base-dev, cmake, pkg-config
  • Fedora: qt6-qtbase-devel, cmake

Quick start

# Build from source (release; slow cold build — fine for packaging)
cargo build --release

# Faster iteration while developing
cargo run -p xzram-cli -- status
make check
make test-lib

# Read-only commands (no root required)
./target/release/xzram status
./target/release/xzram detect
./target/release/xzram doctor

# Stage changes (default) then apply (apply needs polkit / root via helper)
./target/release/xzram zram set --size "min(ram / 2, 4096)"
./target/release/xzram apply

# Immediate apply for scripting
./target/release/xzram zram set --now

Do not use sudo for smoke checks of status / detect / doctor.

Verify

make lint          # fmt --check + clippy -D warnings + loc-check (matches CI)
make test-lib      # fast unit tests for crates/xzram
make test          # full cargo test workspace
make gui-smoke     # Qt6 offscreen launch smoke (needs GUI deps)

Diagnostics: xzram status and xzram doctor are the operator health surface (no root). For binary tracing: RUST_LOG=debug cargo run -p xzram-cli -- status (see docs/DEV-ENV.md).

Optional local git hooks (same gates as CI lint + lib tests):

pip install pre-commit   # or distro package: pre-commit
pre-commit install

See AGENTS.md for agent-oriented bootstrap notes and docs/DEV-ENV.md for test overrides (XZRAM_*).

Installation

From source (recommended for checkouts)

# CLI + daemon + polkit/D-Bus (no Qt)
make install-cli DESTDIR=/tmp/xzram-install
sudo cp -a /tmp/xzram-install/* /

# Or full install including xzram-qt (requires cmake + Qt6)
make install DESTDIR=/tmp/xzram-install
sudo cp -a /tmp/xzram-install/* /

# Optional: enable xzramd for --dbus / other clients (D-Bus activation also starts it on demand)
sudo systemctl enable --now xzramd

Prefer DESTDIR staging over installing as root into the source tree so build-gui/ does not become root-owned. For reinstall/uninstall helpers see scripts/reinstall-system.sh and scripts/uninstall-system.sh. The native GUI uses CLI + pkexec and does not require xzramd.

Build GUI only

make build-gui
# Binary: build-gui/xzram-qt/xzram-qt

Arch / CachyOS / AUR

• Local checkout: root PKGBUILD (file://$startdir) for packaging experiments from a clone.
• AUR: packaging/aur/ — split package xzram + xzram-gui from the v$pkgver GitHub source archive.

# After the package is published on the AUR:
yay -S xzram          # CLI / helper / daemon
yay -S xzram-gui      # Qt6 GUI (depends on xzram)

Release CI (.github/workflows/aur-release.yml) builds the AUR packages in an Arch container and, on a published GitHub Release (v*), uploads .pkg.tar.zst plus pinned PKGBUILD / .SRCINFO to that release. First-time AUR publish is still a manual git push to ssh://aur@aur.archlinux.org/xzram.git using those files (see packaging/aur/README.md).

Debian

dpkg-buildpackage -us -uc -b
sudo dpkg -i ../xzram_*.deb ../xzram-gui_*.deb   # GUI optional
# xzramd is D-Bus-activated; enable optional:
# sudo systemctl enable --now xzramd

Fedora

Build from packaging/xzram.spec with rpmbuild (or your usual RPM workflow). Packages: xzram (CLI/daemon) and xzram-gui (Qt).

CLI reference

xzram status              # all swap devices, zram stats, priorities
xzram doctor              # detect zswap conflict, hibernation issues
xzram detect              # distro, backend, installed packages

xzram zram show|set|disable|migrate
xzram swapfile list|create|resize|remove
xzram swap list|on|off    # list includes fstab partitions
xzram sysctl show|set
xzram defaults recommend|stage|apply
xzram pending show|clear  # inspect/clear staged config
xzram daemon start        # enable and start xzramd (pkexec)
xzram apply               # apply staged configuration
xzram snapshot list       # list configuration snapshots
xzram snapshot restore last-apply
xzram rollback            # alias: restore last pre-apply snapshot

Global flags: --json, --dbus, --now (on write commands)

See docs/SNAPSHOTS.md for snapshot semantics and retention. See docs/RECOMMENDATIONS.md for recommended defaults.

Architecture

xzram CLI / xzram-qt GUI
        │
        ├── read-only ──► xzram lib
        ├── pkexec ──► xzram-helper ──► xzram lib
        └── --dbus ──► xzramd (D-Bus) ──► xzram lib

See docs/SCOPE.md for project scope and docs/GUI-PHASE2.md for the Qt6 GUI and D-Bus daemon architecture.

License

GPL-3.0-or-later. See LICENSE.