Home / Alt manpages / lpstat(1)

  • lpstat(1)
  • User command
  • linux

Check CUPS Printers and Queues with lpstat

Before you touch a print job, use lpstat to see what CUPS actually thinks is happening: scheduler, default printer, queues and devices, all read-only. Nothing here enables, disables, cancels or submits a job. This guide uses lpstat from cups-client 2.4.7-1.2ubuntu7.14; your printer names, jobs and server responses will differ.

The route

Jump straight to the step you need, or tick off Done means at the end.

Give it ten minutes. You need a shell and the cups-client package.

1. Confirm the installed command

Ordinary, unprivileged checks:

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

No dpkg-query? Use your distribution's own package tool. The point is confirming lpstat belongs to the CUPS client tools you actually meant to run, not a stray copy earlier in PATH.

2. Check the scheduler before anything else

$ lpstat -r
scheduler is running

-r reports scheduler state and exits successfully when the query itself works. "scheduler is not running" means start or repair CUPS through your normal service-management process, which is an administrative change, possibly needing sudo, and outside this status check.

Do not treat every non-zero exit as a broken printer. A host with no scheduler can error on printer and queue queries; a running scheduler can still have zero configured destinations.

3. Identify the server and default destination

$ lpstat -H
localhost:631

Then the current default:

$ lpstat -d
system default destination: Office_Printer

"no system default destination" is a valid finding, not a failure: it means nobody configured one for this user and system. Do not invent a destination name off a label stuck to the physical printer. -H shows where the client is talking, it does not change the server; -d reports the default, it does not set one.

4. List printers, devices and accepting state

$ lpstat -p
printer Office_Printer is idle.  enabled since Tue 24 Sep 2026 09:10:00 BST
$ lpstat -v
device for Office_Printer: ipp://print.example.invalid/ipp/print
$ lpstat -a
Office_Printer accepting requests since Tue 24 Sep 2026 09:10:00 BST

Timestamps and device URIs are host-specific. -p reports whether destinations are enabled, -v shows the attached device, -a shows whether the queue accepts new jobs. These overlap but are not the same thing: an enabled printer can still sit behind a queue that refuses new work.

Narrow to a known printer by naming it:

$ lpstat -p Office_Printer
printer Office_Printer is idle.  enabled since Tue 24 Sep 2026 09:10:00 BST
$ lpstat -v Office_Printer
device for Office_Printer: ipp://print.example.invalid/ipp/print

Not sure of the exact name? Leave it off and let lpstat list everything. Printer and class names are case-insensitive but cannot contain spaces, tabs, / or # under CUPS.

5. Inspect pending and completed jobs

Bare, lpstat lists active jobs for the current user. -o lists jobs on named destinations, or everything if you name none:

$ lpstat -o
Office_Printer-42   alice            1024   Tue 24 Sep 2026 09:21:00 BST
$ lpstat -o Office_Printer
Office_Printer-42   alice            1024   Tue 24 Sep 2026 09:21:00 BST

A quiet result just means no matching jobs, not an error. Add -u for a specific user, or leave its argument off for yourself:

$ lpstat -u alice
Office_Printer-42   alice            1024   Tue 24 Sep 2026 09:21:00 BST

To pull in completed jobs, put -W completed before -o and before any printer name:

$ lpstat -W completed -o Office_Printer
Office_Printer-41   alice            2048   Tue 24 Sep 2026 09:05:00 BST

Tip

Ordering is a genuine CUPS trap here. Put -W after -o or after a printer name and the scheduler silently falls back to not-completed, which is also the default value anyway.

lpstat only reports. It does not cancel. Do not chain a status check straight into cancel unless cancelling is an explicit, separately considered decision.

6. Use the combined reports carefully

$ lpstat -s
system default destination: Office_Printer
device for Office_Printer: ipp://print.example.invalid/ipp/print

That combines default destination, classes and devices. For genuinely everything, scheduler state included, use -t:

$ lpstat -t
scheduler is running
system default destination: Office_Printer
device for Office_Printer: ipp://print.example.invalid/ipp/print
printer Office_Printer accepting requests since Tue 24 Sep 2026 09:10:00 BST
printer Office_Printer is idle.  enabled since Tue 24 Sep 2026 09:10:00 BST

Output order, job lines and class lines are server-dependent, so these are illustrative, not a template to parse. If a script needs one fact, reach for the focused option rather than parsing the big -t dump.

7. Diagnose a remote or protected server

-h goes before every other option when you are querying another CUPS server:

$ lpstat -h print-server.example.invalid:631 -r
scheduler is running

The server value can include a port. Keeping -h first also makes a script easier to audit later. Add -E when the connection must be encrypted, and -U USERNAME when the server expects a different authenticated identity:

$ lpstat -E -U printer-auditor -h print-server.example.invalid:631 -p
printer Office_Printer is idle.  enabled since Tue 24 Sep 2026 09:10:00 BST

Warning

Never put a password on the command line or paste credentials into shell history. Authentication, TLS trust and server permissions can all fail this even when the printer itself is fine; if the server is unreachable, check hostname, port, network path and the CUPS logs with whoever runs that server.

Done means

  • Confirmed lpstat is the expected binary from the installed cups-client package.
  • Checked the scheduler with -r and the selected server with -H.
  • Told apart a missing default destination from a stopped scheduler.
  • Used -p, -v and -a to separate printer, device and queue state.
  • Put -W completed before -o when checking completed jobs.
  • Changed nothing: no config, service state or job was touched.