Check a CUPS Print Queue with lpq

Someone says "nothing's printing" and hands you a queue you cannot see yet: lpq is the read-only way to find out what CUPS is actually doing with it. It cannot cancel, submit or alter a job, so you can run it freely while you work out what is stuck. This guide covers checking the default queue, picking a printer, querying a remote server, and watching a queue drain. The examples use CUPS 2.4.7 from the cups-bsd package. Give it ten minutes.

You need a shell, a working CUPS server, and ideally a destination with a job or two in it so you have something real to look at.

1. Confirm the installed command

Check which binary your shell runs and which version it is, before you trust anything it prints:

$ command -v lpq
/usr/bin/lpq
$ dpkg-query -W -f='${Package} ${Version}\n' cups-bsd
cups-bsd 2.4.7-1.2ubuntu7.14

Versions differ between distributions, so the installed manpage is the authority here: it identifies this as CUPS lpq(1) and documents every option below.

2. Query the default destination

Run it bare, no printer name:

$ lpq

With nothing specified, CUPS reports on the default printer or class, and the exact wording depends on your server. An empty queue may say so plainly; a busy one lists each job. Do not lift a sample job number or owner out of this output into an automation script; that data is live, not a template.

No reachable server gives you a failure instead of proof the queue is empty. On this machine, for example:

lpq: Unable to connect to server.

If a script needs to tell success from failure, capture the status straight away:

if output=$(lpq 2>&1); then
    printf '%s\n' "$output"
else
    status=$?
    printf 'lpq failed with status %s\n%s\n' "$status" "$output" >&2
    exit "$status"
fi

An empty queue is a successful run. A non-zero exit is a connection, destination or authentication failure, so surface it to the operator rather than quietly calling it "no jobs".

3. Select a printer or class

Use -P when the default is not the queue you actually need. It takes a destination or class, optionally with an instance after a slash:

$ lpq -P office-laser
$ lpq -P office-laser/draft

Swap office-laser for a name your CUPS server actually knows. If you do not know it, use lpstat -e or your site's printer inventory; lpq has no discovery mode of its own.

A failed named-destination query is still useful: check the spelling, and check you are talking to the server that owns that destination. It will not fix or cancel anything for you.

4. Query a different server

-h has to come before every other option, no exceptions:

$ lpq -h print-server.example.org:631 -P office-laser

The server value can be a host name, address, or host-and-port pair. Port 631 is the usual CUPS port, shown here for illustration; use whatever your administrator actually gave you. This only queries the remote server, it changes nothing on it.

5. Add detail, or check every printer at once

Add -l for the long format when the normal listing is not detailed enough:

$ lpq -P office-laser -l

To ask about jobs on every printer, use -a:

$ lpq -a

Both stay purely reporting options, nothing administrative. -a can dump a lot of output on a shared server, so stick to a named destination while you are troubleshooting one printer. If you combine -h with either, it still goes first: lpq -h print-server.example.org -a -l.

6. Watch a queue until it empties

Prefix a number of seconds with + to repeat the report automatically:

$ lpq -P office-laser +10

That refreshes every ten seconds until the queue is empty. Pick an interval that will not hammer a remote server. Ctrl-C stops the watch, and only the watch: it interrupts the reporting process, not any print job.

Do not mistake the interval for a cancellation timer. A genuinely stuck job needs your normal printer and CUPS troubleshooting, plus a deliberate job-management command once you have confirmed the job's identity and that you are allowed to touch it.

7. Troubleshoot without changing anything

1. Run lpq bare to test the configured default.
2. Run lpq -P DESTINATION with a destination name you have actually confirmed.
3. Run lpq -h SERVER -P DESTINATION, -h first, to test a specific scheduler.
4. Add -l if the connection works but the normal report is too thin to be useful.

None of that needs sudo in the ordinary case. If local policy genuinely demands elevated access, confirm why before you reach for it, and run only the read-only query at the smallest privilege that works. Restarting CUPS, editing printer config or deleting queue files is not a reasonable first response to a failed status check.