Skip to content
PowerBGInfo

Windows, macOS, Linux and headless

What runs where

Windows is supported today. macOS, Linux and headless rendering are in preview: the work is in PowerBGInfo pull request #91 and ships with the next release, together with new DesktopManager and ChartForgeX releases.

Compare capabilities Read pull request #91
PowerBGInfo.Cli --doctor
PowerBGInfo.Cli --doctor
Desktop backend: macos
Available: True
Wallpaper: True
Per-display images: True
Physical display dimensions: True
File rendering: supported without a desktop session
Public AppKit desktop images for the current user's active Spaces/screens. Tile, Span, all-Spaces enumeration and lock screen changes are unsupported.

A rendered image does not prove that a desktop accepted it. Get-BGInfoCapability and the CLI's --doctor report what the current desktop can do before you apply anything.

Real output from the PR #91 build on a Mac. Get-BGInfoCapability returns the same report as an object.

Pick your platform

Each card shows the status today and the shortest way to try it. The full steps for each platform are further down the page.

  • Supported

    Windows

    Windows desktops and servers. PowerShell 5.1 and 7, desktop and lock screen, every monitor, every profile.

    Install-Module PowerBGInfo -Scope CurrentUser
Invoke-BGInfo -Path .\helpdesk.json
# Desktop, lock screen and every monitor
    How to run it on Windows
  • Preview

    macOS

    The current user's wallpaper through AppKit on each reported screen. The lock screen is not available.

    pwsh -c "Install-Module PowerBGInfo"
pwsh -c "Get-BGInfoCapability"
pwsh -c "Invoke-BGInfo -Path ./helpdesk.json"
    How to run it on macOS
  • Preview

    Linux

    GNOME through GSettings and KDE Plasma through D-Bus. Other desktops render to a file.

    pwsh -c "Install-Module PowerBGInfo"
pwsh -c "Get-BGInfoCapability"
pwsh -c "Invoke-BGInfo -Path ./helpdesk.json"
    How to run it on Linux
  • Preview

    Servers and CI

    Render a PNG without a desktop, for documentation, signage or a VM template. Set the width and height yourself.

    New-BGInfo -Target File -ConfigurationDirectory ./out -OutputFileName machine.png {
    New-BGInfoBackground -Width 1920 -Height 1080
    New-BGInfoValue -BuiltinValue HostName -Name 'Computer'
}
# No desktop needed: writes ./out/machine.png
    How to run it on Servers and CI

Capabilities by desktop

One row per job PowerBGInfo does. Linux is split by desktop, because GNOME and KDE Plasma change the wallpaper in different ways.

  • Supported
  • Preview
  • Partial
  • Planned
  • Not supported
  • Not applicable
CapabilityWindowsmacOSLinux, GNOMELinux, KDEServers and CI
Render a wallpaper to a fileSupportedPreviewPreviewPreviewPreviewPass width and height
Apply as the user's wallpaperSupportedPreviewAll Spaces not yet qualifiedPreviewGSettingsPreviewPlasma D-BusNot applicable
One image per monitorSupportedPreviewChecked on one display so farPartialOne image for all screensPartialScreen 0 when screens cannot be listedNot applicable
Lock screenSupportedNot supportedPlannedPlannedNot applicable
All users and the default profileSupportedNot supportedNot supportedNot supportedNot applicable
System factsSupportedWMI and registryPreviewPreviewPreviewPreview
Capability checkPreviewGet-BGInfoCapability and --doctorPreviewPreviewPreviewPreview

Preview statuses follow the PR #91 test record. On macOS, applying, reading back and restoring a wallpaper were checked on a real desktop with one display. GNOME and KDE Plasma have not yet been checked on a real graphical session, and the module and CLI still need their native Linux test run.

Run it on your platform

PowerBGInfo performs one run and exits. Each platform needs the same three decisions: where it runs, which session it runs in, and what refreshes it.

Supported

Windows

The supported platform today. Windows PowerShell 5.1 or PowerShell 7, the desktop and the lock screen, every monitor and, with elevation, every profile on the machine.

  1. Install the module from the PowerShell Gallery for yourself, or for all users on machines that run it unattended.
  2. Build a layout in PowerShell or JSON and render it with -Target File until it looks right.
  3. Choose Wallpaper, LogonScreen or Both with -Target. -AllUsers also writes the wallpaper into every local profile.
  4. Refresh it at sign-in with Task Scheduler, Group Policy, Intune or Configuration Manager.
PowerShell
Install-Module PowerBGInfo -Scope CurrentUser

# Check the image first, then apply it
Invoke-BGInfo -Path .\helpdesk.json -Target File
Invoke-BGInfo -Path .\helpdesk.json -Target Both

Windows guides

Preview

macOS

Preview. PowerBGInfo sets the current user's desktop picture through AppKit on each screen macOS reports. There is no lock-screen or all-users option.

  1. Install PowerShell 7.4 or later. The portable build of the module needs it.
  2. Run Get-BGInfoCapability in your own login session and check that the macos backend is available.
  3. Render with -NoApply and open the PNG before you change anything.
  4. Apply it with -Target Wallpaper.
  5. To refresh it at login or on a timer, run the same command from a LaunchAgent in your account.
PowerShell 7.4+
Install-Module PowerBGInfo -Scope CurrentUser
Get-BGInfoCapability

# Render to a file and look at it first
Invoke-BGInfo -Path ./helpdesk.json -NoApply

# Then set it as your desktop picture
Invoke-BGInfo -Path ./helpdesk.json -Target Wallpaper

macOS guides

Preview

Linux

Preview. GNOME through GSettings and KDE Plasma through its D-Bus scripting interface. On any other desktop PowerBGInfo renders a file and leaves applying it to you.

  1. Install PowerShell 7.4 or later and the module.
  2. Open a terminal inside the graphical session of the user who will see the wallpaper. An SSH session, root or a system account cannot change that desktop.
  3. Run Get-BGInfoCapability to see which desktop backend it found.
  4. Set the image size with New-BGInfoBackground -Width and -Height. The GNOME and KDE adapters do not report physical screen sizes.
  5. GNOME uses one image for every screen, so keep monitor index 0. KDE also needs index 0 when it cannot list its screens.
  6. To refresh it, run the command from a systemd user timer or an XDG autostart entry.
PowerShell 7.4+
# In the user's desktop session, not over SSH
Get-BGInfoCapability

$facts = Get-BGInfoSystemInfo
New-BGInfo -Target Wallpaper -OutputFileName 'machine.png' `
    -ConfigurationDirectory "$HOME/.local/share/PowerBGInfo" {
    New-BGInfoBackground -Width 1920 -Height 1080
    New-BGInfoLabel -Name $facts.ComputerName -FontSize 56
    New-BGInfoValue -Name 'OS' -Value $facts.OSName
    New-BGInfoValue -Name 'Uptime' -Value $facts.UptimeText
}

Linux guides

Preview

Servers and CI

Preview. -Target File never reads or changes a wallpaper, so it runs on a server, in a container or in a CI job with no desktop at all.

  1. Use -Target File with New-BGInfo, -NoApply with Invoke-BGInfo or --no-apply with the CLI.
  2. Give the size with New-BGInfoBackground -Width and -Height. There is no monitor to measure.
  3. Install the fonts the layout uses on the build host. Fonts resolve where the image renders.
  4. Keep paths in JSON relative, so the same file works on Windows, macOS and Linux.
Documentation
Screenshots of a layout for a runbook or a change request.
Signage
A status screen rendered on a schedule and shown by a player.
VM templates
A machine identity image baked into a golden image.
PowerShell 7.4+
$facts = Get-BGInfoSystemInfo
New-BGInfo -Target File -Theme Graphite -OutputFileName 'machine.png' `
    -ConfigurationDirectory ./out {
    New-BGInfoBackground -Width 1920 -Height 1080
    New-BGInfoLabel -Name $facts.ComputerName -FontSize 56
    New-BGInfoValue -Name 'OS' -Value $facts.OSName
    New-BGInfoValue -Name 'Uptime' -Value $facts.UptimeText
}
CLI
PowerBGInfo.Cli --config ./helpdesk.json --no-apply --directory ./out

The CLI writes the image path to standard output and warnings to standard error.

Related

Limits to plan around

These hold for the preview in pull request #91. Each one fails or warns plainly instead of guessing.

  • Lock screen and all users are Windows only

    On macOS and Linux a lock-screen or all-users request fails before anything renders or changes. Use Wallpaper for the current desktop or File for an image.

  • HEIC wallpapers become a plain backdrop

    When the current macOS wallpaper is HEIC or another format the renderer cannot read, PowerBGInfo warns and draws on a plain background. Name a PNG, JPEG, GIF, BMP, PPM or TIFF image, or use a generated background, to keep a photo.

  • Fonts come from the rendering host

    Text uses the fonts installed where the image renders. Install the same licensed fonts on every host where the type must match.

  • Windows paths do not travel

    A Windows-rooted path such as C:\Wallpapers\base.jpg in JSON is rejected on macOS and Linux. Use relative paths, with either slash, or a local absolute path.

  • It must run in the user's session

    Changing a wallpaper needs the graphical session of the user who will see it. An SSH session, a system account or an administrator token does not replace it.

  • Policy can still refuse

    A managed-device policy can block a change that the backend reports as supported. Check the result, not only the render.

Under study Study, not a feature

iPhone and iPad

We are looking at whether PowerBGInfo is useful for Apple mobile devices. Nothing here ships, and nothing here is promised.

What stops it
iOS and iPadOS give apps no way to set the wallpaper, so PowerBGInfo cannot run on the device and change it.
What could work
Device management can set a wallpaper on supervised devices. Microsoft Intune and Jamf are two services that offer it. What each service supports differs, so check yours.
The idea
PowerBGInfo renders one image per device from your inventory, with the asset tag, the owner and a helpdesk QR code, and your MDM delivers it.

Open questions

  • How each MDM takes an image per device rather than one image for a group.
  • Which screen sizes to render for the models in a fleet.
  • How often the image needs refreshing when an owner changes.
  • Drawing a QR code, which PowerBGInfo does not do today.

Would you use this? Tell us in a GitHub issue.

Mock-up of the idea, not a render.