Inspect X Window Geometry and Properties with xwininfo

xwininfo gives you a reliable, shell-driven way to inspect an X window, its geometry and selected properties. The same command can examine the root window, find a window by name or ID, and print a recursive tree when you need to see how an application is laid out.

The examples use xwininfo 1.1.6 from Debian package x11-utils version 7.7+6build2. Allow about ten minutes. You need an X session and a shell with access to its display. This is a read-only diagnostic workflow: it does not move, resize, close or reconfigure windows, and it does not need sudo.

1. Confirm the installed command

Check the binary and its version before relying on an option in a script:

$ command -v xwininfo
/usr/bin/xwininfo
$ xwininfo -version
xwininfo 1.1.6
$ dpkg-query -W -f='${Package} ${Version}\n' x11-utils
x11-utils 7.7+6build2

The version output identifies this installation. The option spelling and details below come from this installed release, not from a desktop environment's window manager.

Checkpoint: If command -v finds nothing, install the distribution package through your normal package-management process. Do not copy a different binary into /usr/bin just to make this example work.

2. Check the display connection

With no -display option, xwininfo uses the DISPLAY environment variable. Inspect it without changing anything:

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

Your value may be different. An empty value normally means the shell is not attached to an X display. A remote display can look like host:0, but only use a host and display you are authorised to access. The X server may also require authentication from an authority file, so do not treat a display error as proof that the server is down.

For a one-off connection to another authorised display, pass it explicitly:

$ xwininfo -display HOSTNAME:0 -root

Replace HOSTNAME:0 with the real display value. This command reads information from that server; it does not start a session there.

3. Inspect a window by selecting it

Run the default command when you want to point at a visible window:

$ xwininfo

The pointer becomes a selector. Click a window with any mouse button. xwininfo then prints a statistics report. The default is effectively -stats, so a normal report includes the window ID, absolute and relative position, width, height, depth, visual and map state.

A shortened report still normally contains lines shaped like these, although values depend on the selected window:

xwininfo: Window id: 0x60000f "example"

  Absolute upper-left X: 2
  Absolute upper-left Y: 85
  Width: 579
  Height: 316
  Map State: IsViewable

Selection is the most common distraction trap. If the command appears to hang, it is usually waiting for the click. Press Ctrl-C to cancel without changing the target or the desktop.

4. Avoid the mouse with a window ID or name

Window IDs are printed by xwininfo and other X utilities. Pass one to -id when the target is hidden, hard to click or needed in a repeatable command:

$ xwininfo -id 0x60000f -stats

The default display is hexadecimal. Add -int when another tool or script expects decimal IDs:

$ xwininfo -id 0x60000f -int -stats

Do not invent an ID. Window IDs are server-specific and can become invalid after a window is closed. A failure for an old ID is a useful indication that the target no longer exists.

If you know the window name instead, use -name:

$ xwininfo -name 'Example editor' -stats

Use the exact name supplied by the X server. If several windows match, or the title changes while you are testing, prefer an ID obtained immediately before the inspection.

5. Inspect the root window and its hierarchy

Use -root for the screen's root window. This avoids selecting a desktop that is completely covered:

$ xwininfo -root -stats

To see the selected window's root, parent and direct children, add -children:

$ xwininfo -id 0x60000f -children

Use -tree instead when you need all descendants recursively:

$ xwininfo -root -tree

Tree output can be large on a busy desktop. Start with -children, then narrow the target by name or ID. It is a read-only query, but it can still produce enough output to bury the lines you actually need in a terminal or log.

6. Ask for the property group you actually need

-all requests every information group: tree, statistics, bits, events, size hints, window-manager hints and shape extents. Convenient for a one-off investigation:

$ xwininfo -id 0x60000f -all

For a smaller and easier-to-parse result, choose one group:

These are observations of the current X server state. They are not instructions to change the application's hints or event subscriptions, and xwininfo has no option here that edits them.

7. Add human-friendly dimensions when geometry matters

Pixel values are the primary measurements. Add -metric to show individual positions and dimensions in millimetres as well, based on the resolution reported by the X server:

$ xwininfo -id 0x60000f -stats -metric

Use -english for inches, with larger units when necessary:

$ xwininfo -id 0x60000f -stats -english

You can request both, but do not confuse either conversion with a physical measurement. The server's reported resolution may not match the monitor's actual density, especially through remote desktop software or display scaling. The -geometry string in the output is also only an estimate: xwininfo documents that it must make assumptions about borders and window-manager behaviour.

8. Diagnose the usual failures

If xwininfo reports that it cannot open the display, check DISPLAY, the X authentication context and whether the target server is reachable. Run the same command as the user who owns the graphical session before trying elevated privileges. sudo can remove the credentials that make an ordinary user able to connect.

If a name or ID fails, obtain a fresh value from the same display and retry. If the command is waiting for a selection, cancel with Ctrl-C rather than clicking an unknown window. If output is too large, replace -all or -tree with the one property group needed for the question.

Done means