Refresh a Damaged X Screen with xrefresh

A dragged window leaves a ghost image behind, and xrefresh clears it without restarting the desktop or closing anything. You will repaint all or part of an X screen on demand. The examples use xrefresh 1.0.7 from the Debian package x11-xserver-utils version 7.7+10build2 installed on this machine.

Allow about five minutes. You need an active X display, permission to connect to it, and a terminal in that display session. This command only triggers repaint events. It does not repair an application that keeps drawing corrupted content.

1. Confirm the command and target display

Check which executable will run, then inspect the DISPLAY value:

$ command -v xrefresh
/usr/bin/xrefresh
$ xrefresh -version
xrefresh 1.0.7
$ printf '%s\n' "${DISPLAY-}"
:0

The last line must identify the X server you intend to refresh. A value such as :0 selects the local display; a value such as host.example:1 selects a server and screen according to the X display syntax. If the line is empty, do not guess. Run the command from the graphical session, or set DISPLAY to a verified value:

$ export DISPLAY=:0

This variable tells the client where to connect. It does not grant access. If the command reports that it cannot open the display, check the session and X authorisation before trying other options. Do not copy an xhost + command from an untrusted suggestion: broad X access can let another client observe or control the session.

Checkpoint: xrefresh -version can succeed even when the display is unset, because it exits before connecting. The real display check happens when you run a refresh option.

2. Refresh the entire screen with the default mode

Run the command with no background option:

$ xrefresh

The default is -none. xrefresh maps a temporary window over the target area and immediately unmaps it, causing applications to receive repaint events. With this default, the temporary window has no background, so the screen should repaint without a deliberate black or white flash. Normally there is no useful standard output.

Run it again if a window still looks stale. A second refresh is harmless and does not alter application files, window geometry or desktop configuration. If the same application immediately redraws the defect, the refresh worked but the application's own rendering remains the problem.

3. Use a solid background only when you want a visible flash

The solid modes are useful for making the repaint boundary obvious, but they are less comfortable for normal use:

$ xrefresh -white
$ xrefresh -black
$ xrefresh -solid green

-white makes the screen appear to flash white. -black briefly makes it go black and can be disorienting. -solid takes a colour name such as green. These modes still only cause a repaint; they do not set the root window background or change a theme.

Prefer the default for a routine refresh. Before using a solid mode in a shared display session, warn anyone looking at the screen. There is no rollback step because these options do not persist: when the temporary window is unmapped, the underlying windows repaint normally.

4. Refresh only a rectangle

Use -geometry when one region is damaged and you want to avoid disturbing the rest of the screen. Its value is a width, height and position in X geometry notation:

$ xrefresh -geometry 800x600+40+80

This targets an 800 by 600 rectangle whose top-left corner is 40 pixels from the left edge and 80 pixels from the top edge of the screen. The option describes the area to repaint; it is not a request to resize the display or the application windows inside it.

Keep the values positive and use coordinates that fit the intended screen. If you omit -geometry, xrefresh targets the whole screen. If the damaged area crosses monitors, identify the X screen layout first rather than assuming that a single rectangle maps cleanly to your desktop arrangement.

Checkpoint: After a regional refresh, inspect the untouched part of the desktop as well as the rectangle. If only the rectangle changes, the scope was applied. If the result is not useful, rerun plain xrefresh to repaint everything.

5. Select another display explicitly

Use -display when the shell's default is not the server you need:

$ xrefresh -display :1

Replace :1 with a display value that you have verified. A remote display also requires network reachability and X authorisation. The command cannot bypass those controls, and adding permissive access rules is not a routine troubleshooting step.

When a display connection fails, capture the exact error and check these ordinary causes:

The last case matters because xrefresh is an X client. It cannot repaint a native Wayland surface. If an Xwayland display exists, target that display; otherwise use the compositor or application-specific diagnostic appropriate to the Wayland session.

6. Keep the configuration trap in view

xrefresh reads X resources through XGetDefault(3). The documented resource names are capitalised: Black, White, Solid, None, Root and Geometry. The manual calls the geometry resource not very useful, so command-line options are clearer when you need a one-off, reviewable action.

Do not assume that a shell variable or a lower-case resource name changes the program. For a predictable repair, put the complete option on the command line and record the display value used. The command has no service to restart and normally needs no elevated privileges. Using sudo can make the client lose the X authorisation that your ordinary user already has.

Done means