wpSYNC follows your GNOME wallpaper and prepares it for the GDM login screen and, when explicitly configured, your existing GRUB theme. Choose an image in GNOME Settings or use Set as Background in Files; the same watcher coordinates both destinations. The original image stays unchanged.

flowchart LR
    desktop["GNOME desktop<br/>Active light or dark wallpaper"] --> sync["wpSYNC<br/>Watch · prepare · validate"]
    sync --> gdm["GDM login screen<br/>Adjustable blur"]
    sync -. "Optional setup" .-> grub["GRUB boot screen<br/>Centered, unblurred JPEG"]
    classDef source fill:#e0f2fe,stroke:#0369a1,color:#0c4a6e
    classDef process fill:#ede9fe,stroke:#7c3aed,color:#4c1d95
    classDef optional fill:#fef3c7,stroke:#b45309,color:#78350f
    class desktop,gdm source
    class sync process
    class grub optional

The first release supports the following environment:

Other distributions, GNOME versions, immutable Fedora variants such as Silverblue, multiple wallpaper owners and multi-seat setups are outside this release's supported scope. GDM's wallpaper is system-wide: different accounts cannot each own a separate login image through this installation.

Check your environment from a terminal in your desktop session:

cat /etc/fedora-release
gnome-shell --version
printf 'Session type: %s\n' "$XDG_SESSION_TYPE"

Expect Fedora 44, GNOME Shell 50.x and session type wayland. These commands are informational; the installer separately checks Fedora and GNOME versions. Do not treat a successful file preview as a full compatibility test.

Before continuing, save your work, choose an image you are comfortable showing before login, and let any package or theme installation finish. Keep your source images and any personally customized theme backed up separately. wpSYNC's recovery copies are not a substitute for a system backup.

Scope of boot changes: optional GRUB synchronization replaces the configured background.jpg, maintains background.previous.jpg, and uses temporary sibling files during replacement. It preserves the theme's theme.txt, fonts, scrims, icons and selection graphics. It does not regenerate grub.cfg, change /etc/default/grub, alter EFI variables, kernels, initramfs, partitions or disk encryption. These are implementation boundaries, not a claim of zero risk.

Run installation as your normal desktop user, from a local graphical session. Do not prefix ./install.sh with sudo; the installer elevates only its system phase. Use Fedora's system Python, not a pip virtual environment.

Use a trusted clone, extracted repository ZIP, or packaged source release. For the 0.1.0 release archive, put the archive and its checksum file in the same directory, then run:

sha256sum --check wpSYNC-0.1.0.tar.gz.sha256
tar -xzf wpSYNC-0.1.0.tar.gz
cd wpSYNC-0.1.0

The checksum check should report wpSYNC-0.1.0.tar.gz: OK. Stop if it fails. For another release, substitute that release's version in the filenames. If you already cloned or extracted the repository, open a terminal in the directory containing install.sh and README.md instead.

./install.sh --help
./install.sh --plan

The plan lists the system/user destinations and the selected synchronization targets. It does not install packages or services or change wallpaper files. It is a file preview, not a dependency or live-theme acceptance check.

On a fresh installation, GRUB is disabled. On an upgrade, omitting GRUB options preserves the existing configuration. To explicitly request GDM-only operation, use --without-grub for both preview and installation; see updates if GRUB is already configured.

For the default fresh GDM-only installation:

./install.sh

The installer:

1. Checks supported Fedora/GNOME versions and missing RPM packages.
2. Offers to install missing dependencies, then validates the schema and runs tests.
3. Requests installation confirmation and uses sudo for system files.
4. Installs the user worker, extension, Files integration and CLI.
5. Enables the extension now, or queues activation for the next login.
6. Offers to close Nautilus windows so its menu provider can load.

Save any ongoing Files operations before accepting a Nautilus restart. The installer does not restart GDM, log you out or reboot. Automatic synchronization can begin as soon as the extension is active.

./install.sh --yes --install-deps

If GNOME has not discovered the extension, save your work and log out/in when convenient. Restart Nautilus when ready to load its menu integration. Then run:

gnome-extensions info wallpaper-sync@mouge
gnome-extensions prefs wallpaper-sync@mouge
wallpaper-sync --version
wallpaper-sync sync
wallpaper-sync status

Keep Synchronize wallpapers on. Follow current desktop wallpaper enables automatic following; turn that off if you prefer to use Sync Now manually. The master switch must remain on for manual synchronization too.

For a successful check, sync should finish without an error, and status should report the selected source and the latest backend state. A disabled GRUB backend is expected on a fresh GDM-only installation. If an error is reported, read the backend details: one destination may already have succeeded.

No immediate reboot is needed to install or validate generated files. Passing unit tests or seeing a matching checksum does not establish that your firmware, GRUB theme or GDM greeter has rendered the result correctly.

Choose this only if you already have a working GRUB theme that uses a static background.jpg under /boot/grub2/themes/<theme>/. wpSYNC does not install, select or redesign a theme. Confirm the theme's theme.txt references that file; its existing wallpaper must pass the helper's JPEG and trusted-path checks. The theme must already be selected in your boot setup. wpSYNC does not reveal a hidden GRUB menu or change its display mode.

flowchart TD
    start["Do you want boot wallpaper sync?"] --> want{"Enable GRUB?"}
    want -->|No| gdm["Install GDM-only<br/>Fresh default, or --without-grub"]
    want -->|Yes| exists{"Existing supported theme<br/>using background.jpg?"}
    exists -->|No| defer["Use GDM-only for now<br/>Theme installation is a separate task"]
    exists -->|Yes| plan["Preview with theme name and size"]
    plan --> install["Install with the same options"]
    install --> check["Run sync and inspect status"]
    check --> inspect["Check appearance at the next normal boot"]
    classDef safe fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef decision fill:#fef3c7,stroke:#b45309,color:#78350f
    class gdm,defer,inspect safe
    class want,exists decision

For an existing Tela theme at /boot/grub2/themes/tela, using an output size of 2880 × 1800:

./install.sh --plan --grub-theme tela --grub-size 2880x1800
./install.sh --grub-theme tela --grub-size 2880x1800
wallpaper-sync sync
wallpaper-sync status

Replace tela and the dimensions with your actual theme and desired output. --grub-theme takes a directory name, not a path. Each dimension must be 64–8,192 pixels, with at most 8,294,400 total pixels. The option sizes the image; it does not change the firmware/GRUB display mode.

The derivative respects EXIF orientation, fills the chosen dimensions without stretching, crops centrally, flattens transparency over black and removes metadata. It is an 8-bit, non-progressive RGB JPEG, without GDM's blur. Important content near an image's edges may be cropped.

Both the root configuration and Sync GRUB boot wallpaper preference must allow synchronization. wallpaper-sync grub-enable resumes an already configured backend; it cannot authorize a new theme or destination. See the GRUB guide for processing and transaction details.

Open preferences with gnome-extensions prefs wallpaper-sync@mouge. Fresh defaults are master sync on, automatic following on, source active light/dark, GDM blur 12, conversion on, notifications off, and GRUB off unless configured during installation.

Local input is limited to 64 MiB, 16,384 pixels per side and 64 megapixels. TIFF uses its first frame. Remote URLs, slideshow schedules and SVG wallpapers are unsupported. Decoder availability determines whether each listed raster format can be read.

Pausing does not restore or delete an image. It prevents new work and cancels stale user-side preparation. A request already executing in the privileged helper may still finish and install its image. Use the action that matches your intention:

GDM restoration uses the verified original for the currently installed Fedora GNOME package, not necessarily your pre-install custom theme. GDM recovery copies are created during GDM operations, not merely by completing installation.

GRUB restoration validates both the live and previous image; a damaged live image can prevent CLI restoration even when a backup exists. There may be no previous image before the first successful change. The corresponding synchronization switch remains off if restoration fails. Turning a switch off cannot undo an operation that already committed.

If you want to remove wpSYNC and also undo its most recent GRUB change, restore GRUB before removing the helper or disabling its installation configuration:

# Only if GRUB is configured and you want its previous image back:
wallpaper-sync restore-grub

# Then remove the application; accept GDM restoration if desired:
./uninstall.sh

Uninstallation preserves source images, desktop wallpaper settings, recovery backups, and user cache/status. Dependency RPMs are not automatically removed. Those retained files can contain earlier wallpapers and source paths. Keep recovery copies until the system's appearance is verified; consult the recovery guide before deleting them.

Obtain the new trusted source, then run these as the same owner:

./install.sh --plan
./install.sh

Existing preferences and configured GRUB settings are preserved when their options are omitted. A recognized earlier Tela-enabled installation migrates with its 2880 × 1800 profile; an older GDM-only installation stays GDM-only.

To remove GRUB support during an update, first run wallpaper-sync restore-grub if you want the previous boot image back, then:

./install.sh --plan --without-grub
./install.sh --without-grub

After a Fedora/GNOME package update or separate GRUB theme installation, wait for that operation to finish, then run wallpaper-sync sync and inspect status. There is no package-manager or theme-directory hook. A new GNOME package requires its matching original resource; unexpected modifications or a missing verified baseline cause a refusal. A Fedora/GNOME major-version upgrade can also move you outside this release's supported scope.

Start with inspection commands:

wallpaper-sync status
wallpaper-sync doctor
gnome-extensions info wallpaper-sync@mouge
journalctl --user -u wallpaper-sync.service -n 50 --no-pager
journalctl -u wallpaper-sync-helper.service -n 50 --no-pager

System journal access may require administrator privileges. Redact usernames, private image paths, URIs and other sensitive details before posting output.

Do not run GRUB generators/installers, rebuild an initramfs, disable SELinux, or restart GDM as generic wallpaper troubleshooting steps.