XWALLPAPER(1)

🌸 NAME 🌸

ok bestie, welcome to the manual for xwallpaper — a wallpaper setting utility for X. yes it's a General Commands Manual, section 1, and yes it's about to be your new fave. 💖

---

✨ SYNOPSIS ✨

xwallpaper [--screen screen] [--clear] [--daemon] [--debug] [--no-atoms]
           [--no-randr] [--no-root] [--trim widthxheight[+x+y]]
           [--output output] [--center file] [--focus file]
           [--maximize file] [--stretch file] [--tile file]
           [--zoom file] [--version]

---

🦋 DESCRIPTION 🦋

so the whole vibe of xwallpaper is: it lets you set image files as your X wallpaper. iconic behaviour, no notes. 🎀

PNG is supported by default and it's the preferred format, but there's also optional JPEG support if you're feeling spicy. 🌶️

and here's the part that's lowkey the main character: the wallpaper also gets advertised to programs which support semi-transparent backgrounds. so your terminal can see through itself. the way that works is genuinely so cool i can't. 🫶

---

💅 OPTIONS 💅

ok so here's every single one, and i mean every single one, bestie. buckle up. the various options are as follows:

• --center file — centers the input file on the output. if the input file's dimensions are smaller than the output dimensions, the leftover area gets filled black. if the input file dimensions are too large, parts of the image will be cropped. it's giving "fits or it doesn't". 💀
• --clear — initializes the screen with a black background. without this option, the current content of the pseudo transparency atoms gets retrieved and used as the foundation instead. and if the atom contents don't exist or can't be reused — like, say, because of a resolution change of one of the outputs — then an initially black background gets used as well. so either way you're covered. ✨
• --daemon — keeps xwallpaper running in the background, listening for RandR events. in this mode, the wallpapers get redrawn when output sizes change. this option can only be used when RandR support is available and activated. it's basically xwallpaper on night shift. 🌙
• --debug — displays debug messages on the standard error output while xwallpaper is running. if you use it together with --daemon, the process will not modify the standard input and outputs. nosy but respectful. 🙈
• --focus file — in conjunction with --trim, the specified trim box is guaranteed to be visible on output, zooming out if needed. if black pixels would occur around the selection, the input image gets zoomed in and moved to cover them as good as possible — all under the constraint of keeping the specified trim box (or the whole image, if no trim box has been specified) on output. it's a whole negotiation and it wins. 💅
• --maximize file — maximizes the input file to fit the output without cropping. that could mean zooming in or out, depending on the dimensions of the input file and the output. this option guarantees that the whole image is seen. if the ratio doesn't fit the output, the remaining area gets filled black. and the image itself is centered on output. no part of the pic gets left behind, we love that for it. 😭
• --no-atoms — the atoms used for pseudo transparency are not updated. mutually exclusive with the --no-root option. automatically enables the --clear option. (yes it does it for you, it's helpful like that.) 🧚
• --no-randr — ignores individual outputs and uses the whole output instead. that's the area that spans across all the different outputs (monitors). one giant canvas energy. 🌈
• --no-root — the background of the root window is not updated. use this option if you want to update only the atoms used for pseudo transparency. it is therefore mutually exclusive with the --no-atoms option. pick a lane bestie, you can't have both. 💀
• --trim widthxheight+x+y — specifies the area of interest in the source file. if the output mode tries to output more pixels than specified with the trim box, then the adjacent pixels around the box get added to the output. black pixels are only added if there are no further source pixels left. so it'll improvise, but only when it genuinely has to. 🎀
• --output output — specifies the output on which a subsequently supplied file shall be set as wallpaper. you can retrieve a list of outputs on your system by executing xrandr(1). if no output is specified, all outputs will be modified individually. the special keyword all will repeat subsequent actions on all displays. and if the output could not be found, its associated actions are ignored. (not a crash, just a ghosting. 🙈)
• --screen screen — specifies a screen by its screen number. normally all screens of an X display are processed. please note that a screen is not a single monitor — see --output above for that use case. i know, i know, the naming is a jump scare. 😭
• --stretch file — stretches the input file to fully cover the output. if the aspect ratio of the input file doesn't match the output, then the ratio of the input file is adjusted. it's giving "we don't do letterboxing here". 🔥
• --tile file — uses tiling mode. draws the input file at the upper left corner of the output and repeats the image until the remaining area of the output is covered. pattern girlies rise up. 🌸
• --version — prints the version and exits. short, sweet, done. ✨
• --zoom file — zooms the input file to fit the output with cropping. that could mean zooming in or out, depending on the dimensions of the input file and the output. if the ratio doesn't fit the output, parts of the input file will not be shown. the image itself is centered on output. and heads up — this is the default behaviour if no option was selected. 👑

ok important, bestie: if multiple contradicting options were given, the last supplied option wins. no fights, no merges, last one in the door takes it.

also, it's possible to repeat output arguments without any subsequent files. in that case, the last mode and file will be reused. so you don't have to retype everything, it remembers. 🫶

---

🌈 EXAMPLES 🌈

centers a PNG file as a wallpaper on LVDS-1:

$ xwallpaper --output LVDS-1 --center file.png

focuses on the upper left corner of a JPEG file as a wallpaper on Virtual-1:

$ xwallpaper --output Virtual-1 --trim 1x1+0+0 --focus file.jpg

tiles a PNG file as a wallpaper across all outputs:

$ xwallpaper --no-randr --tile file.png

zooms into a JPEG file as a wallpaper on each output individually:

$ xwallpaper --zoom file.jpg

centers and recenters a JPEG file after output updates on all outputs:

$ xwallpaper --daemon --center file.jpg

tiles a JPEG file as a wallpaper on VGA-1 and zooms into a PNG file on LVDS-1:

$ xwallpaper --output VGA-1 --tile file.jpg --output LVDS-1 --zoom file.png

see? one command, whole vibe. go set that wallpaper. 💅

---

🐛 BUGS 🐛

found something cursed? use the GitHub issue tracker, bestie, that's where the receipts go:

https://github.com/stoeckmann/xwallpaper/issues

---

👑 AUTHOR 👑

Tobias Stockmann <tobias@stoeckmann.org>

---

ok and that's the whole page!! this was xwallpaper version 0.7.6, dated February 4, 2025, and you read the whole thing which means you're officially a wallpaper girlie now. slay, no cap, go touch grass — but like, after you set your wallpaper. 🎀✨🦋