A live topographic wallpaper for Linux (Wayland), Windows and macOS. Your desktop becomes a slowly breathing contour map of real terrain — from a globe lit by the actual sun, down through mountain ranges and valleys, to the runs and lifts of a single ski resort — with a quiet clock and the weather in the corner.
Watch it live — a quiet minute over Bridger Bowl.
- Real terrain anywhere on Earth. Type a place ("Zermatt", "Yosemite", "Hokkaido") and topopaper builds a map of it from open elevation and OpenStreetMap data, then flies there.
- One continuous atlas. Every map is linked to the globe, so flights zoom smoothly from the planet down to a valley and back.
- Alive, but calm. Contours drift, the camera breathes, the day/night line and aurora follow the real sun, and the wallpaper freezes when windows cover it so it costs nothing while you work.
- Clock and weather (Open-Meteo, no account needed), themes, multi-monitor, and a settings app.
- Linux: a Wayland compositor that supports wlr-layer-shell: Sway/SwayFX, Hyprland, niri, river, Wayfire, KDE Plasma 6, and most wlroots-based compositors. GNOME is not supported (it has no layer-shell). OpenGL ES 2 (any GPU driver, or Mesa's software renderer), Python 3, GTK 4 and libadwaita (the installer handles this on Arch, Debian/Ubuntu, Fedora, openSUSE, Void and Alpine).
- Windows 10 or 11 (64-bit) with an OpenGL 2 graphics driver (every current GPU has one), and Python 3.9 or newer (the installer offers to install it with winget).
- macOS 10.15 or newer, the Xcode command line tools, and Python 3.9 or
newer with Tk (the one from python.org, or
brew install python python-tk).
How each system is supported, and what differs: docs/PLATFORMS.md.
Linux and macOS, in a terminal:
curl -fsSL https://raw.githubusercontent.com/aidenwboudr/topopaper/main/install.sh | bashor from a checkout: git clone https://github.com/aidenwboudr/topopaper && topopaper/install.sh.
The installer checks your desktop, offers to install missing system packages
on Linux (it shows the exact command first), builds the wallpaper, installs
it into ~/.local, downloads the starter globe (~30 MB), and asks whether to
start at login and whether to add a Super+Shift+B search shortcut.
Nothing in your compositor config changes without a yes.
Windows, in PowerShell:
irm https://raw.githubusercontent.com/aidenwboudr/topopaper/main/install.ps1 | iexIt downloads the prebuilt wallpaper from the latest release into
%LOCALAPPDATA%\Programs\topopaper, sets up Python for the map builder, adds
Start menu entries, downloads the globe, and asks about starting at sign-in
and a Win+Shift+B search shortcut. No administrator rights needed.
Then open Topopaper from your app launcher or Start menu (or run
topopaper-settings) and tell it where home is.
To remove it: ./uninstall.sh (keeps your maps and settings) or
./uninstall.sh --purge; on Windows, uninstall.ps1 in the install folder
(-Purge deletes the maps and settings too).
| Settings | topopaper-settings — maps, theme, clock and weather, motion, displays, autostart |
| Go somewhere | Super+Shift+B (Win+Shift+B on Windows; on macOS make one in the Shortcuts app), or topopaper-ctl search — pick a map or type any place |
| Fly to a map | topopaper-ctl fly zermatt (no name: the next map) |
| Start / restart / stop | topopaper-ctl restart, topopaper-ctl stop |
| Lock screen to match | topopaper-ctl snapshot lock.png saves the wallpaper as it is now, without the clock (Linux); see below |
| Something wrong? | topopaper-ctl doctor checks the install and your desktop |
| Everything else | topopaper-ctl --help |
Building a new map takes a few minutes (the data comes from public servers);
the wallpaper keeps running and flies there when it's ready. The first map in
a new part of the world also gets a few coarser in-between maps so it zooms
smoothly out to the globe — those finish in the background and can take a
while when the public map servers are busy. Maps you searched
for are kept until you delete them in Settings → Places, or clean up old ones
with topopaper-ctl gc.
Settings live in ~/.config/topopaper/config.ini (Windows:
%APPDATA%\topopaper\config.ini) — the settings app edits it, and so can
you; the wallpaper picks up changes within a second.
topopaper-ctl autostart enable sets this up for you on every system (on
Windows a sign-in entry, on macOS a LaunchAgent). If you'd rather add it to
your compositor config yourself on Linux, run topopaper-session at startup:
| compositor | line |
|---|---|
| Sway | exec topopaper-session |
| Hyprland | exec-once = topopaper-session |
| niri | spawn-at-startup "topopaper-session" |
| river / Wayfire / others | run topopaper-session from your autostart |
| KDE Plasma | System Settings → Autostart → add topopaper-session |
topopaper-ctl snapshot OUT (.png, .jpg or .ppm) saves the map on
screen right now at your largest display's resolution. Point a lock screen at
it so locking keeps the same view. For swaylock, bind this as your lock
command (PPM is the quickest to write, so the lock doesn't lag):
topopaper-ctl snapshot "$XDG_RUNTIME_DIR/lock.ppm"; swaylock -f -i "$XDG_RUNTIME_DIR/lock.ppm"hyprlock and gtklock take the same file as their background image.
topopaper talks to a few public services, only when it needs to: elevation tiles (AWS Open Data), OpenStreetMap's Overpass and Nominatim (when you build a map or search), Photon (spelling suggestions), Open-Meteo (weather), and — only if you leave the weather location on automatic — an IP-geolocation service. Automatic locations are rounded to about 11 km before being used anywhere. Nothing else leaves your machine, and there is no telemetry.
Maps are built from open data. If you share screenshots or maps, please keep the credits:
- Map data © OpenStreetMap contributors, available under the ODbL.
- Elevation: AWS Terrain Tiles (Mapzen Terrarium; SRTM, GMTED, ETOPO1, USGS NED and others) and the Copernicus DEM GLO-30 (© DLR e.V. 2010–2014 and © Airbus Defence and Space GmbH 2014–2018, provided under COPERNICUS by the European Union and ESA).
- Lakes on the globe: Natural Earth (public domain).
- Weather: Open-Meteo (CC BY 4.0).
- Geocoding: Nominatim and Photon.
- Font: JetBrains Mono (SIL Open Font License 1.1).
Please be kind to the free public servers: topopaper rate-limits itself and caches everything it downloads.
A small C engine draws the map with OpenGL: on a Wayland layer-shell surface, behind the desktop icons on Windows, at desktop level on macOS. Everything else (map building, search, weather, the settings app) is Python. See docs/ARCHITECTURE.md for the pieces, docs/PLATFORMS.md for the per-system parts and CONTRIBUTING.md to hack on it.
topopaper is free software under the GNU General Public License v3.0 or
later. The bundled JetBrains Mono font is under the SIL Open Font
License 1.1 (data/fonts/OFL.txt); the generated Wayland protocol files keep
their MIT-style licenses.