Read a CUPS Print Queue Safely with lpq

You will use lpq to inspect pending jobs in a CUPS printer queue, choose a particular destination, request more detail, and watch a queue until it drains. The examples use CUPS 2.4.7 from the cups-bsd package installed on this machine. Allow about ten minutes. You need a shell, a working CUPS server and at least one destination if you want to see real queue entries.

This guide is read-only. lpq does not submit, cancel or alter jobs, so the examples do not need elevated privileges. If a destination or server is protected by local policy, use the account and authentication method already approved for that system rather than adding permissions just to inspect it.

1. Check the installed command

Confirm which executable your shell will run and record the package version:

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

Package versions differ between distributions. The local manual is the authority for this installation; its page identifies the command as CUPS lpq(1) and documents the options used below.

2. Query the default destination

Run lpq without a printer name:

$ lpq

With no destination option, CUPS reports jobs for the default printer or class. The exact output depends on the server and queue. A queue with no pending jobs may say that it is empty; a queue with jobs normally identifies the printer and lists each job. Do not copy a sample job number or owner into an automation script, because those values are live data.

On a machine with no reachable CUPS server, this command fails instead of proving that the queue is empty. For example, this machine currently reports:

lpq: Unable to connect to server.

Capture the status immediately when a script needs to distinguish success from failure:

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

A successful command can report an empty queue. A non-zero status is a connection, destination, authentication or other command failure, so show it to the operator instead of silently treating it as "no jobs".

3. Select a printer or class

Use -P when the default is not the queue you need. The value can be a destination or class, and it can include an instance after a slash:

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

Replace office-laser with the name configured on your CUPS server. Use lpstat -e or your site's printer inventory to discover destination names if you do not know them. lpq itself does not provide a printer-discovery mode.

A failed named-destination query is useful evidence: check the spelling and whether the destination belongs to the server you are contacting. It does not cancel or repair a queue.

4. Query a different server

Put -h before every other option. The installed manual explicitly requires this ordering:

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

The server value is a host name, address or host-and-port pair. Port 631 is shown here because it is the usual CUPS service port, but use the port supplied by your administrator when it differs. The command contacts that server for this query; it does not change server configuration.

5. Add detail or inspect every printer

Add -l for the long reporting format when the normal listing does not contain enough detail:

$ lpq -P office-laser -l

To ask for jobs on all printers, use -a:

$ lpq -a

These are reporting options, not administrative operations. They may produce a large result on a shared server, so prefer a named destination when you are troubleshooting one printer. If you combine -h with either form, keep it first, for example lpq -h print-server.example.org -a -l.

6. Watch a queue until it is empty

Prefix an interval in seconds with + to repeat the report:

$ lpq -P office-laser +10

This asks for a new listing every ten seconds and continues until the queue is empty. Choose an interval that does not create unnecessary load on a remote server. Stop the watch with Ctrl-C if you no longer need it; that interrupts the reporting process, not the print jobs.

The interval is not a cancellation timer. If a job is stuck, investigate the printer, CUPS service and job details using your normal operational runbook. Use a separate, deliberate job-management command only after confirming the job identity and the required authorisation.

7. Troubleshoot without changing state

Work through these checks in order:

1. Run lpq without options to test the configured default.
2. Run lpq -P DESTINATION with a confirmed destination name.
3. Run lpq -h SERVER -P DESTINATION, keeping -h first, to test a specific scheduler.
4. Repeat with -l if the connection succeeds but the normal report lacks useful detail.

Inspecting with lpq does not require sudo in the normal case. If a local policy genuinely requires elevated access, verify the reason first and run only the read-only query with the smallest approved privilege. Do not restart CUPS, edit printer configuration or remove queue files as a first response to a failed status check.