Set an X Root Window Background Safely with xsetroot

You will finish with a repeatable way to change the background of an X root window, try a solid colour or pattern, and restore the familiar default. The changes are live for the selected X display, but they are not persistent unless you place a working command in 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 the 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 be different. If it is empty, xsetroot will usually fail 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 understood by the X server. 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 provide the result you expect.

4. Try the built-in patterns

Only one background-changing choice may be used in one invocation. Choose one of -solid, -gray, -grey, -bitmap or -mod. Do not combine them and expect 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. That behaviour is easy to miss when 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 background colour for the pattern, while -solid sets the whole root window to one colour. -rv exchanges foreground and background colours when 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 default 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 its 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 to be reinstated.

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, omit cursor options so you do not change another visible setting.

-name sets the root window name, but the manual notes that 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 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 that the file is readable and was created as an X bitmap, rather than assuming any image file will work.

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