How to check which monitors are connected on Linux from the command line

Use xrandr --query to list all display outputs and whether a monitor is physically connected to each one.

Prerequisites

xrandr talks to a running X11 server, so all of the following must be true:

An X server is already running (e.g. the kiosk startx session on DISPLAY=:0). On a headless box with no X running, this will not work.
x11-xserver-utils is installed (sudo apt-get install x11-xserver-utils) — it provides xrandr.
You have permission to talk to the X server. If you are logged in as the user that started X (over SSH or a console), DISPLAY=:0 alone is enough. As a different user (e.g. root querying a session owned by kiosk), you also need XAUTHORITY pointing at that user’s ~/.Xauthority file, otherwise you get:

error.txt

Authorization required, but no authorization protocol specified

Can't open display :0

The command

Querying the kiosk user’s X session as root:

example.sh

sudo XAUTHORITY=/home/kiosk/.Xauthority DISPLAY=:0 xrandr --query

If you are the kiosk user, just DISPLAY=:0 xrandr --query.

Example output

output.txt

Screen 0: minimum 320 x 200, current 1920 x 1080, maximum 16384 x 16384
DisplayPort-0 connected primary 1920x1080+0+0 (normal left inverted right x axis y axis) 479mm x 260mm
   1920x1080     60.00*+  50.00    59.94
   1600x1200     60.00
   1680x1050     59.95
   1280x1024     75.02    60.02
   1440x900      74.98    59.89
   1280x960      60.00
   1152x864      75.00
   1280x720      60.00    50.00    59.94
   1024x768      75.03    70.07    60.00
   832x624       74.55
   800x600       72.19    75.00    60.32    56.25
   720x576       50.00
   720x480       60.00    59.94
   640x480       75.00    72.81    66.67    60.00    59.94
   720x400       70.08
DisplayPort-1 connected (normal left inverted right x axis y axis)
   1920x1080     60.00 +  50.00    59.94
   1600x1200     60.00
   1680x1050     59.88
   1280x1024     75.02    60.02
   1440x900      74.98    59.90
   1280x960      60.00
   1152x864      75.00
   1280x720      60.00    50.00    59.94
   1024x768      75.03    70.07    60.00
   832x624       74.55
   800x600       72.19    75.00    60.32    56.25
   720x576       50.00
   720x480       60.00    59.94
   640x480       75.00    72.81    66.67    60.00    59.94
   720x400       70.08
DisplayPort-2 disconnected (normal left inverted right x axis y axis)
DisplayPort-3 disconnected (normal left inverted right x axis y axis)

How to read it

Each line starting with a connector name (DisplayPort-0, HDMI-1, DP-1, …) is one physical output on the GPU.
connected means a monitor is plugged in and responding. DisplayPort-0 also shows its active mode 1920x1080+0+0 (resolution plus X/Y offset in the framebuffer) and primary.
connected without a mode (like DisplayPort-1 above) means a monitor is plugged in but currently has no mode set — it’s not displaying anything yet.
disconnected means nothing is plugged into that port.
In the mode list under each output, * marks the currently active mode and + marks the monitor’s preferred (native) mode.

Count connected monitors in a script

example.sh

xrandr --query | grep -c ' connected '
# → 2 for the example above

Or list just the names of connected outputs:

example.sh

xrandr --query | grep ' connected ' | cut -d' ' -f1

output.txt

DisplayPort-0
DisplayPort-1

Note the space after connected — it prevents disconnected from matching.

Also see How to run a second program on a second screen with Chromium kiosk on Ubuntu and How to setup Chromium Kiosk on Ubuntu 26.04 in 30 seconds.