Inspect X11 Atom Names with xlsatoms

You will use xlsatoms to list the interned atoms known to an X server, search for one by name, and check a chosen numeric range. The command only queries the server. It does not change atoms, windows or desktop settings.

Allow about five minutes if an X display is already available. You need the x11-utils package and permission to connect to the target X server. No root access is normally needed.

1. Check the installed command and display

This guide describes xlsatoms 1.1.4 from the installed Debian package x11-utils version 7.7+6build2. The program uses the DISPLAY environment variable unless you provide -display explicitly.

$ command -v xlsatoms
/usr/bin/xlsatoms
$ xlsatoms -version
xlsatoms 1.1.4
$ printf 'DISPLAY=%s\n' "${DISPLAY:-<unset>}"
DISPLAY=:0

Your display value will differ. If DISPLAY is unset, set it only to a display you are authorised to use, for example export DISPLAY=:0 on a local graphical session. A display name is not a password and does not grant access by itself.

2. List the atoms on the default display

With no range or name, xlsatoms starts at atom value 1 and lists atoms until it reaches an unknown value. Each line contains the numeric value followed by the atom name. The default format is a tab between those fields.

$ xlsatoms
1 PRIMARY
2 SECONDARY
3 ARC
4 ATOM
5 BITMAP
6 CARDINAL
7 COLORMAP

The exact list depends on the X server and the clients that have connected to it. The first few protocol-defined atoms are a useful connectivity check, but do not treat the complete output as a stable inventory. A running desktop can intern more names while you are looking at the list.

If the command reports that it cannot open the display, check DISPLAY, your session's X authorisation and whether the server is running. Do not use sudo as a first response: root can still lack the correct authorisation cookie, and changing users can hide the real problem.

3. Search for one atom by name

Use -name when you know the name you want to check. This avoids scanning a long listing and is useful for confirming names used by window tools or scripts.

$ xlsatoms -name WM_NAME
39 WM_NAME

The numeric value is assigned by the server and can differ between servers or sessions. If the name does not exist, xlsatoms prints a diagnostic on standard error. Treat that as a negative result, not as a request to create the atom.

$ xlsatoms -name THIS_ATOM_SHOULD_NOT_EXIST
xlsatoms: no such atom name "THIS_ATOM_SHOULD_NOT_EXIST"
$ printf 'exit status: %s\n' "$?"
exit status: 1

The wording and exit status are from the installed utility and should be checked on your host if a script depends on them. Keep the name quoted when it comes from a shell variable.

4. Inspect an explicit numeric range

Use -range when you need to examine particular numeric values. Its syntax is [low]-[high]. An omitted low value means 1. An omitted high value makes xlsatoms stop at the first undefined atom at or above the low value.

$ xlsatoms -range 1-20
1 PRIMARY
2 SECONDARY
3 ARC
4 ATOM
5 BITMAP
6 CARDINAL
7 COLORMAP
8 CURSOR
9 CUT_BUFFER0
10 CUT_BUFFER1

When both bounds are present, the command tries every value in the range, including values that have no definition. That makes an explicit range useful for finding gaps, although the output may contain fewer lines than the number of values requested.

$ xlsatoms -range 1-3
1 PRIMARY
2 SECONDARY
3 ARC
$ xlsatoms -range 100-
100 some-server-specific-name

The names and values in these examples are display-dependent. Use the command's actual output as your evidence; do not copy a number from one machine into a script that runs against another X server.

5. Make output easier to parse

The -format option accepts a printf-style string. xlsatoms supplies the atom value as an unsigned long and the name as a character string, in that order, then adds a newline to each result. The default is %lu\t%s.

$ xlsatoms -range 1-7 -format 'value=%lu name=%s'
value=1 name=PRIMARY
value=2 name=SECONDARY
value=3 name=ARC
value=4 name=ATOM
value=5 name=BITMAP
value=6 name=CARDINAL
value=7 name=COLORMAP

Quote the format string so the shell does not interpret spaces or other punctuation. Keep the two conversions in the documented order. If another program consumes the output, test it with atom names containing spaces or punctuation before relying on a simple field split.

6. Query another display without changing your session

Pass a display name with -display when the target is not the one in DISPLAY. This is still a read-only query, but the target may contain sensitive window or session metadata. Use a display you are authorised to inspect.

$ xlsatoms -display :1 -name WM_CLASS
67 WM_CLASS

Do not put an untrusted display string into a shell command without quoting it. For a one-off query, an environment override keeps your current shell unchanged:

$ DISPLAY=:1 xlsatoms -name WM_CLASS
67 WM_CLASS

Neither form modifies DISPLAY permanently. There is no undo step because xlsatoms performs no persistent operation.

Common traps

• Confusing atoms with windows: an atom is a server-side numeric name for a string. xlsatoms does not list windows, processes or window geometry.
• Assuming values are portable: names such as WM_NAME are useful across X clients, but their numeric values belong to the server session.
• Expecting an exhaustive stable list: the default scan stops at the first unknown value. Use an explicit range when you need to inspect later values or gaps.
• Redirecting diagnostics away: a missing atom name is reported on standard error. Capture both streams when recording a troubleshooting run.
• Using elevated privileges: sudo xlsatoms can lose the original X authorisation context. Run as the logged-in desktop user unless your environment explicitly requires another identity.