Set an X Root Window Background Safely with xsetroot

The default grey mesh behind your windows gets old fast, and xsetroot swaps it for a solid colour or a pattern, live on the X display. This guide covers trying a background, restoring the familiar default, and knowing which changes are actually persistent. The changes only last for the selected X display unless you add a working command to your X startup configuration.

This guide covers xsetroot 1.1.3 from Debian package x11-xserver-utils version 7.7+10build2. Allow about ten minutes. You need a running X server, permission to connect to it, and a shell. These examples do not need sudo.

1. Confirm the installed command

Check the binary and its version first. This is read-only and does not contact an X server:

$ command -v xsetroot
/usr/bin/xsetroot
$ xsetroot -version
xsetroot 1.1.3
$ dpkg-query -W -f='${Package} ${Version}\n' x11-xserver-utils
x11-xserver-utils 7.7+10build2

The long option names in these examples match the installed manual. The command also accepts -d and -display for selecting a server, and -def and -default for restoring unspecified attributes.

2. Check the display connection

In a normal graphical terminal, xsetroot uses the display named by DISPLAY. Inspect it before making a change:

$ printf 'DISPLAY=%s\n' "$DISPLAY"
DISPLAY=:0

Your value may differ. If it is empty, xsetroot usually fails because it has no server to contact. If you are working with another local or remote X server, pass its exact display name explicitly:

$ xsetroot -display DISPLAY_NAME -solid navy

Replace DISPLAY_NAME with a real value such as :0 or host.example:0. Do not guess a remote display name, and do not weaken X authentication just to make this test work.

3. Set a temporary solid background

Use -solid followed by a colour name the X server understands. This changes the root window immediately:

$ xsetroot -solid '#20242b'
$ printf 'exit status: %s\n' "$?"
exit status: 0

The hexadecimal value is quoted so the shell passes it as one argument. A zero exit status means the request completed; it does not make the colour persistent. The installed manual describes -solid as useful on colour servers, so a monochrome or unusual X server may not give you the result you expect.

4. Try the built-in patterns

Only one background-changing choice can be used per invocation. Pick one of -solid, -gray, -grey, -bitmap or -mod. Do not combine them expecting the last one to win.

For a plain grey background, use either spelling:

$ xsetroot -grey

For a plaid-like grid, provide two integers from 1 to 16:

$ xsetroot -mod 4 8

Zero and negative values are treated as 1 by this version, which is easy to miss when the values come from a script, so validate inputs yourself if the pattern matters. Foreground and background colours apply to -mod, -bitmap and cursor operations, not to a solid background:

$ xsetroot -fg white -bg '#20242b' -mod 4 8

Here -bg means the background colour for the pattern, while -solid sets the whole root window to one colour. -rv swaps foreground and background colours wherever a pattern or cursor uses them:

$ xsetroot -rv -mod 2 2

5. Restore the default state

Use the restore command after testing, or whenever an experiment leaves the desktop confusing:

$ xsetroot -def
$ printf 'exit status: %s\n' "$?"
exit status: 0

With no options, or with -def, xsetroot resets the root window to its default state: the manual describes that as a familiar grey mesh and a hollow X cursor. Because -def resets unspecified attributes, you can combine it with a specific change when you want everything else returned to default:

$ xsetroot -def -solid '#20242b'

This restores unspecified attributes and then requests the solid background. If you changed another person's display, rerun xsetroot -def against that same display, or repeat the original command if a particular desktop setup needs reinstating.

6. Add a cursor or root-window name only when needed

xsetroot can also change the pointer cursor outside application windows. -cursor_name selects a standard cursor-font name, without the XC_ prefix:

$ xsetroot -cursor_name left_ptr

Cursor names are separate from background choices. A bitmap cursor needs both a cursor bitmap and a mask bitmap, while -xcf takes an Xcursor file and a size. Do not invent file paths or names. If you only wanted to test a background, leave cursor options out so you do not change another visible setting.

-name sets the root window name, but the manual notes it is not useful for iconifying the background. It is not required for ordinary desktop background work.

7. Diagnose failures without escalating privileges

If xsetroot reports that it cannot open the display, check DISPLAY, the X session, and your X authentication. Running it as root does not automatically grant access to another user's display, and it can create confusing ownership or environment problems.

If a colour or cursor name is rejected, try a simple known value such as white or black, then check the X server's colour and cursor support. If a pattern looks wrong, check that both -mod values are integers in the documented 1 to 16 range. If you used a bitmap, verify the file is readable and was actually created as an X bitmap, rather than assuming any image file will work.

For a startup file, prove the command works interactively first. Then add exactly that command to the session's existing X startup mechanism, keep it unprivileged, and remember the display may not be ready the moment the startup file runs. A failed startup command should not stop the rest of the session from starting, so test changes in a disposable session or keep a way to remove the line.