Inspect an X Display Safely with xdpyinfo

xdpyinfo dumps everything an X server is willing to tell you about itself: screens, visuals, protocol extensions, the lot, in one read-only query. This guide uses the installed xdpyinfo 1.3.4 from Debian package x11-utils 7.7+6build2.

Allow about ten minutes. You need a shell and access to an X display. No elevated privileges are normally required. The command does not configure the X server, change its screen settings or alter persistent files.

1. Check the installed utility

Start by confirming which executable your shell will run and which version it reports. The version query does not touch an X server at all, so it also works from a headless shell:

$ command -v xdpyinfo
/usr/bin/xdpyinfo
$ xdpyinfo -version
xdpyinfo 1.3.4

Your path may differ. The checkpoint here is simply that the command is the expected X utility with a known version. -version answers that question; it does not query the server.

2. Confirm the display name

Without -display, xdpyinfo reads the host, display number and screen from the DISPLAY environment variable. Check it before running anything:

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

Replace :0 with whatever your own session reports. A remote X display often looks like host.example:10.0. This is connection information, not a file path, so do not tack on a slash or point it at some arbitrary socket.

Checkpoint: run the smallest useful query and see the server answer:

$ xdpyinfo | sed -n '1,24p'
name of display:    :0
version number:    11.0
vendor string:    The X.Org Foundation
vendor release number:    12401000
X.Org version: 1.24.1
maximum request size:  16777212 bytes
motion buffer size:  256
bitmap unit, bit order, padding:    32, LSBFirst, 32
image byte order:    LSBFirst
number of supported pixmap formats:    7
...

Exact values depend on your server. A successful run just means the utility connected and got display information back; it says nothing about whether every X extension is actually available to every client.

3. Separate connection errors from server details

Wrong or missing DISPLAY and the utility never even reaches a server:

$ DISPLAY= xdpyinfo
xdpyinfo:  unable to open display "".

Wording and punctuation can vary slightly, but the diagnosis is always the same: this shell has no usable display name. Set DISPLAY to the value belonging to the session and retry. On a remote login, also check that X forwarding was actually requested and that the forwarded value made it into the environment.

Warning: do not reach for sudo xdpyinfo as a general fix. Privilege escalation can lose the original DISPLAY and X authentication credentials entirely, while buying you no useful access. Keep the command unprivileged unless your administrator has set up a specific, tested access arrangement.

4. Inspect one extension

The default report covers general server information, screens and visuals, but skips numeric protocol-extension data such as opcodes, base events and base errors. Use -ext when you need details for one named extension:

$ xdpyinfo -ext RANDR | sed -n '1,40p'
name of display:    :0
...
X-Resource extension not supported by server

That sample diagnostic is deliberately host-dependent. If your server supports the requested extension, you get extension-specific details instead. Use an exact extension name the server accepts, and treat an "unsupported" message as a finding, not a command failure to paper over.

-ext all asks for details on every extension both xdpyinfo and the server understand, which can be a wall of text. Stick to one extension when you are chasing a specific client problem.

5. Query extension protocol numbers only when needed

Reach for -queryExtensions when a diagnostic actually needs the numeric extension information:

$ xdpyinfo -queryExtensions | sed -n '/number of extensions:/,/^$/p'
number of extensions:    23
    BIG-REQUESTS
        opcode:    134
        base event:    0
        base error:    0
    Composite
        opcode:    142
        base event:    0
        base error:    0

The extension count and numbers are only an example of the output's shape, not portable constants. Do not parse them as fixed positions. If you're automating this, capture the report for the same server family and make the parser tolerate extensions being added or removed.

Safety boundary: the local manpage warns that this option can make servers which load extensions dynamically load all of them at once. That can be slow and can chew through server resources. Save it for a real protocol investigation, not a routine health check, and do not run it repeatedly against a busy or fragile display server.

6. Choose a reproducible diagnostic command

For a support record, capture the display name, version and a bounded report in one shell session:

$ printf 'display: %s\n' "${DISPLAY:-<unset>}"
display: :0
$ xdpyinfo -version
xdpyinfo 1.3.4
$ xdpyinfo | sed -n '1,80p' > /tmp/xdpyinfo-report.txt
$ sed -n '1,20p' /tmp/xdpyinfo-report.txt
name of display:    :0
...

This writes a temporary report under /tmp; it does not touch the X server. Clean up once you are done sharing or reviewing it:

$ rm -- /tmp/xdpyinfo-report.txt

Warning: that removal is irreversible for the local copy. Check the path carefully before pressing Enter. If the report contains hostnames or other environment details, treat it as operational information and share it only with the intended recipient.

Done means