ICEWMBG(1)

📦
version 4.1.0 · 17 versions
, in arch rolling

💅 icewmbg — the manual, but make it make sense

okay so bestie, gather round. this is icewmbg, and it's the desktop background image manager for IceWM (that's the one-line NAME bit, consider it folded in 🎀). it's giving "i make your desktop pretty and i take it very seriously."

✨ SYNOPSIS ✨

icewmbg [OPTIONS] [ARGUMENTS]

🦋 DESCRIPTION 🦋

so icewmbg can slap a colour or an image onto your X11 desktop background. common image formats? supported, obviously. and every single icewm(1) workspace can have its own background — like each one is a different era of you 💖.

when the background image changes, icewmbg can be notified to update the background. when you're switching workspaces it checks the image file's modification time, and if that's changed it reloads the image. lowkey smart.

it also supports semitransparency — semitransparent background images and colours can be configured. yes ma'am.

it uses RandR or Xinerama to support backgrounds on all your connected monitors, so when monitors appear/disappear or change their resolution, icewmbg will adjust. there's also an option for one giant background spread over all monitors, if that's your vibe.

it updates the "_ICEWMBG_IMAGE" property of the root window to the path of the background image whenever it changes the desktop background. periodt.

icewmbg is started automatically by icewm-session(1). and here's the cute part: if there's just a single background for all workspaces, icewmbg may conclude it can safely exit after setting the desktop background, to free its system memory. if the screen size changes, icewm will then attempt to restart icewmbg, preferably via icewm-session. icon behaviour honestly.

🎀 ARGUMENTS 🎀

💜 SPECIFIC OPTIONS

where multiple values can be given for images or colours, they're separated by comma's. each such value may be enclosed in double quotes ". if FILE is a directory, all images from that directory are used in sorted order. and if the value starts with an exclamation mark, as in !FILE, the images from the directory FILE are permuted randomly 🙈. image file names or directory names may have glob(7) wildcards, or they may start with a tilde or environment variable.

  • -f, --fork — fork into the background and detach from the terminal. bye bestie 👋
  • -p, --replace — replace an existing icewmbg. if there's a running icewmbg, it's instructed to quit, and the new icewmbg takes over. main character energy only.
  • -q, --quit — tell the running icewmbg to quit. this option is used by icewm-session(1) when icewm(1) exits.
  • -r, --restart — tell the running icewmbg to restart itself. useful when settings in have changed. if no icewmbg is active, it starts one.
  • -u, --shuffle — shuffle the list of background images randomly. you can give this option again whenever the running icewmbg should reshuffle its list of background images 🔀.
  • -c, --config=FILE — load preferences from FILE.
  • -t, --theme=THEME — use the theme named THEME.
  • -i, --image=FILE[,FILE]* — load background images from each FILE. this overrules the "DesktopBackgroundImage" preference. when more than one image is given, they're assigned to each workspace in the given order.
  • -k, --color=COLOR[,COLOR]* — use background colours from each COLOR. this overrules the "DesktopBackgroundColor" preference.
  • -s, --semis=FILE[,FILE]* — load transparency images from each FILE. this overrules the "DesktopTransparencyImage" preference.
  • -x, --trans=NAME[,NAME] — use transparency colours for each NAME. this overrules the "DesktopTransparencyColor" preference.
  • -e, --center={0|1} — disable/enable centring background. this overrules the "DesktopBackgroundCenter" preference.
  • -a, --scaled={0|1} — disable/enable scaling background. this overrules the "DesktopBackgroundScaled" preference.
  • -m, --multi={0|1} — disable or enable a single background over all monitors. this overrules the "DesktopBackgroundMultihead" preference.
  • -y, --cycle=SECONDS — cycle over the list of background images every SECONDS. this overrules the "CycleBackgroundsPeriod" preference.
  • -o, --output=FILE — redirect all output to FILE. a leading tilde or environment variable is expanded.
  • --postpreferences — print a list of all preference values that icewmbg will use.
  • --verbose — print a log of actions and some events.

🌈 GENERAL OPTIONS

  • -d, --display=DISPLAY — use DISPLAY to connect to the X server. otherwise use DISPLAY from the environment.
  • -h, --help — print a brief usage statement to stdout and exit.
  • -V, --version — print the program version to stdout and exit.
  • -C, --copying — print copying permissions to stdout for the program and exit.
  • --sync — use a slow synchronous mode to communicate with the X11 server. ngl it's slow on purpose.
  • --verbose — report on some of the activities.

🍓 FILES 🍓

additional arguments, which either are a path or which have an image extension, are assumed to be background image files or directories. iykyk.

🌸 PREFERENCES 🌸

by default icewmbg loads settings from the icewm(1) preferences file. see icewm-preferences(5) for details. the settings read are:

DesktopBackgroundCenter    - Display desktop background centered
DesktopBackgroundScaled    - Display desktop background scaled
DesktopBackgroundColor     - Desktop background color(s)
DesktopBackgroundImage     - Desktop background image(s)
ShuffleBackgroundImages    - Shuffle the list of background images
SupportSemitransparency    - Support for semitransparent terminals
DesktopTransparencyColor   - Semitransparency background color(s)
DesktopTransparencyImage   - Semitransparency background image(s)
DesktopBackgroundMultihead - One background over all monitors
CycleBackgroundsPeriod     - Seconds between cycling over backgrounds

if these settings are set in the preferences file, they can be overridden by the theme in the theme defaults file. to enforce a certain setting, set it in the prefoverride file instead — see icewm-prefoverride(5). no cap, that's the way to lock it in 🔒.

🧚 WORKSPACES 🧚

each workspace can have a unique image. specify multiple images to DesktopBackgroundImage separated by comma's, or give at least one directory with images. the images are assigned to each workspace in the order given. when icewm changes workspace, the running icewmbg will adapt the desktop background to the assigned image. it just knows 💅.

if you specify more images than there are workspaces, then CycleBackgroundsPeriod can set a period. when the period expires, icewmbg will switch to the next set of images. if you give less images than there are workspaces, then icewmbg will reuse previous images for the remaining workspaces. recycling queen 🌿.

⭐ IMAGE SCALING ⭐

often a background image has a different width or height than the screen. the image can then be replicated (tiled), centered or scaled. this is controlled by "DesktopBackgroundCenter" and "DesktopBackgroundScaled". what happens for their combination is given by the following table:

center:0 scaled:0 = The background is replicated in both directions.
center:1 scaled:0 = The background is centered, but not scaled.
center:1 scaled:1 = Fill one dimension and preserve the aspect ratio.
center:0 scaled:1 = Fill both dimensions and preserve the aspect ratio.

🔥 EXAMPLES 🔥

# For four unique desktop backgrounds for four workspaces do:

icewmbg -f -p -i image0,image1,image2,image3

# Or create a directory with the four images and do:

icewmbg -f -p -i /path/to/directory

# The images should have proper image filename extensions.

(that last line is a comment, not a command — pls don't run it 😭 the images should have proper image filename extensions, fr fr.)

👑 SIGNALS 👑

icewmbg supports the following signals:

  • SIGHUP — icewmbg will restart itself.
  • SIGINT, SIGTERM — icewmbg will terminate. 💀
  • SIGUSR1 — icewmbg will reshuffle the list of background images and update the backgrounds of all workspaces.

🫶 SEE ALSO 🫶

icewm(1), icewm-preferences(5), icewm-prefoverride(5), wmsetbg(1), xsetbg(1), xwallpaper(1).

😭 BUGS 😭

please report bugs at <https://github.com/ice-wm/icewm/issues>. do it for the culture.

💖 AUTHOR 💖

Brian Bidulock <mailto:bidulock@openss7.org>.

see --copying for full copyright notice and copying permissions.

🌟 LICENSE 🌟

IceWM is licensed under the GNU Library General Public License. see the COPYING file in the distribution or use the --copying flag to display copying permissions.

ok that's the whole thing, nothing skipped, you're welcome 💅✨

and that's a wrap bestie 🎀 — this little love letter ships as part of icewm 4.1.0, dated 2026-08-06. now go set a cute wallpaper, you've earned it 🌈🦋

📦 where this page comes from