FreeBSD Manual Pages
ICEWMBG(1) User Commands ICEWMBG(1)
NAME
icewmbg - a desktop background image manager for IceWM
SYNOPSIS
icewmbg [OPTIONS] [ARGUMENTS]
DESCRIPTION
icewmbg can assign a colour or image to the X11 desktop background. Common
image formats are supported. Each icewm(1) workspace can have its own
background.
When the background image changes, icewmbg can be notified to update the
background. When switching workspaces, it checks the image file modifica-
tion time. If it has changed, it reloads the image.
icewmbg supports semitransparency. Semitransparent background images and
colours can be configured.
It uses RandR or Xinerama to support backgrounds on all connected monitors.
When monitors appear/disappear, or change their resolution, icewmbg will
adjust. It supports an option for one large background over all monitors.
It will update the "_ICEWMBG_IMAGE" property of the root window to the path
of the background image whenever it changes the desktop background.
icewmbg is started automatically by icewm-session(1). If there is just a
single background for all workspaces, icewmbg may conclude that it can
safely exit after setting the desktop background, to free its system mem-
ory. If the screen size changes, icewm will then attempt to restart
icewmbg, preferably via icewm-session.
ARGUMENTS
SPECIFIC OPTIONS
Where multiple values can be given for images or colours, they are sepa-
rated 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 or-
der. If the value starts with an exclamation mark, as in !FILE, the images
from the directory FILE are permuted randomly. Image file names or direc-
tory 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.
-p, --replace
Replace an existing icewmbg. If there is a running icewmbg, it is in-
structed to quit. The new icewmbg will take over.
-q, --quit
Tell the running icewmbg to quit. This option is used by icewm-ses-
sion(1) when icewm(1) exits.
-r, --restart
Tell the running icewmbg to restart itself. This is useful when set-
tings in have changed. If no icewmbg is active, it starts one.
-u, --shuffle
Shuffle the list of background images randomly. This option may be
given 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 "Desktop-
BackgroundImage" preference. When more than one image is given, they
are assigned to each workspace in the given order.
-k, --color=COLOR[,COLOR]*
Use background colours from each COLOR. This overrules the "Desktop-
BackgroundColor" preference.
-s, --semis=FILE[,FILE]*
Load transparency images from each FILE. This overrules the "Desktop-
TransparencyImage" preference.
-x, --trans=NAME[,NAME]
Use transparency colours for each NAME. This overrules the "Desktop-
TransparencyColor" preference.
-e, --center={0|1}
Disable/Enable centring background. This overrules the "DesktopBack-
groundCenter" preference.
-a, --scaled={0|1}
Disable/Enable scaling background. This overrules the "DesktopBack-
groundScaled" preference.
-m, --multi={0|1}
Disable or enable a single background over all monitors. This over-
rules 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.
--verbose
Report on some of the activities.
FILES
Additional arguments, which either are a path or which have an image exten-
sion, are assumed to be background image files or directories.
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).
WORKSPACES
Each workspace can have a unique image. Specify multiple images to Desktop-
BackgroundImage 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 back-
ground to the assigned image.
If you specify more images then there are workspaces, then CycleBack-
groundsPeriod 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 work-
spaces.
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 con-
trolled 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.
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>.
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 copy-
ing permissions.
icewm 4.0.0 2026-01-01 ICEWMBG(1)
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=icewmbg&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>