A replacement for aging paid alternatives for applying multi monitor spanning wallpapers.
A menu bar app, and the command line tool underneath it. macOS 14 or later. No dependencies, no subscription. The CLI never touches the network. The app only does so to check for updates when you ask or turn that on, and to send a daily usage ping, which is on by default and has an off switch.
- Spans one wallpaper across all your displays as a single continuous image.
- Compensates for bezels, so the picture lines up to your eye.
- Corrects for differing pixel density, so an image is the same real-world size on each screen.
- Helps you align your monitors, so the cursor crosses each seam where the picture does.
- Cycles a folder on an interval, in the background and across logins.
Stable:
brew install --cask serubin/tap/wallspan
# or
brew tap serubin/tap
brew install --cask wallspanBeta:
brew install --cask serubin/tap/wallspan@beta
# or
brew tap serubin/tap
brew install wallspan@betaUpgrading or switching casks turns cycling off, so choose Enable Cycling again after.
Without Homebrew, grab Wallspan-<version>.zip from the latest prerelease on the
releases page.
Wallspan lives in the menu bar.
- Choose Folder… - pick a folder of images. Avoid Desktop, Documents and Downloads: the background agent can't ask for permission there, so it fails quietly.
- Change Every - 5 minutes to a day.
- Enable Cycling.
Next Wallpaper changes it now. Pause Cycling stops the schedule, and stays paused across reboots.
Enable Cycling installs a LaunchAgent that keeps running after you quit the app and across logins. Open Wallspan at Login is separate and only brings the menu bar item back.
macOS places displays edge to edge, with no way to describe the bezels between them, so a spanned image breaks across each seam. wallspan models each panel in millimetres, so the part of the image behind a bezel is hidden, not squeezed into view.
Displays ▸ Calibrate… draws a test pattern over every screen without touching your wallpaper. Line up the long diagonals across each bezel:
- Position - arrow keys, or drag a screen. Diagonals stepping down-right across a seam mean the gap is too small, up-right too large. Your main display stays put.
- Scale - Panel scale, or ⌥↑ / ⌥↓. Use it when circles break across a seam but the diagonals line up.
Align in System Settings… then lines up the macOS display arrangement vertically to
match, which decides where the cursor crosses between screens. It shows the change first.
Revert to Saved or wallspan layout arrange --revert restores the arrangement you had
before wallspan.
macOS reads each panel's size from EDID, and monitors often get it wrong. One LG here claims 109 PPI across but 111 PPI down, which no real panel has. wallspan keeps the reported diagonal, which EDID rounding barely moves, and forces square pixels. That removes the non-square error without asking.
A size wrong by the same proportion on both axes looks consistent, so only your eye can
catch it - that's what Panel scale is for. A ⚠︎ in the Displays submenu means a stored
size still implies non-square pixels. Set both axes with wallspan layout size.
The app changes your wallpaper and layout by running wallspan, and the CLI covers what
the app doesn't.
wallspan info # your displays, and how they're mapped
wallspan preview img.jpg -o out.png # see the crop without touching anything
wallspan apply img.jpg # span it across every display
wallspan cycle ~/Pictures/Backgrounds --interval 15m
wallspan restore # back to your wallpaper from before wallspan
wallspan status # what is on screen, and what is next
wallspan next
wallspan pause
wallspan resumewallspan config set --dir ~/Pictures/Backgrounds --interval 15m
wallspan agent install
wallspan agent uninstallEnable Cycling runs agent install --binary with the wallspan the app is using, while
plain agent install copies the CLI into ~/.local/bin.
Settings live in ~/Library/Application Support/wallspan/config.json, and a running agent
picks up changes within seconds:
{
"idleDeferSeconds" : 5,
"intervalSeconds" : 900,
"playlistDirectory" : "/Users/you/Pictures/Backgrounds",
"recursive" : false,
"shuffle" : true
}idleDeferSeconds holds a scheduled change until there's been no keyboard or mouse input
for that many seconds, waiting at most half an interval or five minutes, whichever is
shorter. --idle-defer off turns it off. Logs go to
~/Library/Logs/wallspan.log.
wallspan calibrate # set the test pattern as wallpaper
wallspan layout nudge dell --dx 20px --dy -4px
wallspan layout size lg --ppi 109.6 # or --width 797.22mm from the spec
wallspan layout show
wallspan layout reset # back to edge to edge
wallspan layout arrange [--dry-run | --revert]
wallspan verify-mapping <image|directory> # check the rendered output
wallspan restore # when you are donePause cycling first, or the next change replaces the pattern.
The app has no wallpaper logic of its own. It runs whichever wallspan is on your PATH,
and falls back to the copy in its bundle if that one is missing or speaks a contract
version the app doesn't understand. The JSON contract
between them is versioned.
About Wallspan… shows which copy is in use and why.
defaults write net.serubin.wallspan.app PreferBundledCLI -bool true pins it to the
bundled one. Install CLI… symlinks the bundled CLI into ~/.local/bin when no other
wallspan is installed.
Off until you turn on Check for Updates Automatically, or choose Check for Updates…. A check is one unauthenticated request, and automatic ones run at most once a day:
https://api.github.com/repos/Serubin/WallSpan/releases/latest
Beta installs ask for releases?per_page=10 instead, since latest skips prereleases.
That does tell GitHub the install follows betas. Only tag_name, draft and
prerelease are read. The request carries no identifier, no cookies, and a bare
User-Agent: Wallspan and Accept-Language: en, so it doesn't leak your app version,
macOS build or languages.
Nothing downloads or updates itself. You get a menu entry pointing at the release page,
or at brew upgrade if Homebrew installed it. A failed automatic check stays silent.
The menu bar app tells the project's own Plausible server that it was running today. It exists to answer whether anyone uses this, and it is the only thing sent without you asking. Turn off Send Daily Usage Ping in the menu to stop it. The first launch sends nothing, so you have until the next day to do that.
It is one POST a local day to https://analytics.serubin.net/api/event, with the same
body from every install of a version. A failed one retries hourly, so a response lost on its
way back can count you twice:
{"name":"pageview","url":"app://wallspan/1.0.0","domain":"wallspan.serubin.net"}The app version is the only thing that varies, and following a beta or rc does put you in a
smaller group. There is no identifier and no cookies, and User-Agent and Accept-Language
are pinned to Wallspan and en. The date of the last ping stays on your Mac. As with any
web request, the server sees your IP address. Plausible uses it to derive a country and a
visitor hash salted with a key it deletes daily, and doesn't store the address itself.
The CLI sends nothing, so only people running the app are counted. Only release, beta and rc builds signed with the project's Developer ID send it, so unsigned releases, hand builds and forks send nothing.
- Per-Space wallpaper. macOS keeps a wallpaper per Space. Cycling applies the image to
each Space as you arrive, but a one-shot
wallspan applyonly reaches the current one. Setting a wallpaper costs macOS about 2.4s of CPU whatever the image, so cycling skips Spaces that already have it. - One
cycleat a time. A second one exits and names the pid holding the lock. - The render cache never evicts. It lives in
~/Library/Application Support/wallspan/renderedand is safe to delete. - Some of the image is discarded. Anything behind a bezel, or above and below a shorter
screen, isn't shown - roughly a third of the source with an ultrawide beside a portrait
panel.
wallspan layout showprints the figure. - An image that already matches one display exactly still gets scaled and cropped, since it's mapped across the whole arrangement.
swift build -c release
Scripts/make-app.sh # builds dist/Wallspan.app
swift testNeeds only the Command Line Tools Swift toolchain and no signing certificate. swift test
needs Xcode.
wallspan version prints which channel a build came from:
| channel | example | from | signed |
|---|---|---|---|
release |
0.2.0 |
the releases page | Developer ID, notarised |
beta |
0.2.0-beta.3, 0.2.0-rc.1 |
a prerelease, and wallspan@beta |
Developer ID, notarised |
unsigned |
0.2.0-unsigned.1 |
a test of the release workflow | ad-hoc |
snapshot |
0.2.1-snapshot.7+g1a2b3c4 |
each merge to main, as a CI artifact |
ad-hoc |
dev |
0.2.1-dev.pr42+g1a2b3c4 |
a pull request, as a CI artifact | ad-hoc |
Each release ships the app, the CLI as a tarball and a bare binary, and SHA256SUMS.txt.
The first run of a downloaded CLI needs a network connection, so macOS can check its
notarisation. Ad-hoc builds are blocked by Gatekeeper once downloaded.
Cutting a release is covered in docs/releasing.md.
GPL-3.0-or-later. See LICENSE.
GPL so it can't become a closed paid product like the tools it replaces: anyone who distributes it must share the full source under the same terms. It's written from scratch against public AppKit APIs, with no code taken from any existing product.
Made and maintained by a 15-year software veteran with the help of AI.