Cancel the Right CUPS Job with lprm

A single hyphen turns lprm from a scalpel into a machine that cancels every job on the queue, so it pays to know exactly what you are about to remove. This guide covers finding the right job, targeting the right printer and server, and the two commands that catch people out. Examples use lprm from cups-bsd 2.4.7-1.2ubuntu7.14, at /usr/bin/lprm.

Give it ten minutes. You need a shell, access to the destination that owns the job, and the job ID itself. Inspecting is ordinary user territory; cancelling changes queue state and cannot be undone by lprm, so identify the job properly before you run the destructive step.

1. Confirm the installed command

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

A read-only sanity check on the syntax:

$ lprm --help
Usage: lprm [options] [id]
       lprm [options] -

The options you will actually use: -P for a destination, -h for a server and port, -U for a username, and -E to force encryption. Local help confirms the syntax; the manpage explains what each one means.

2. List jobs before you touch anything

Use lpstat -o to see what is queued. It never calls lprm and never changes anything:

$ lpstat -o

Columns and layout depend on your CUPS server. Treat the job ID as data to copy exactly, not a printer name. An empty list means there is nothing here to cancel; an error means fix the destination or server first.

3. Cancel one identified job

For a job on the default destination, pass its ID:

$ lprm JOB_ID

Replace JOB_ID with the value from lpstat -o, say 1234. lprm may print a server response, or finish silently, and silence is not proof you hit the right queue. Check again:

$ lpstat -o

Job gone: it was cancelled, or something else already removed it. Job still there: check destination and server against what you actually inspected, and do not just guess and retry.

There is no undo for a cancelled job. If the document is still needed, pull it from its original source and resubmit once you have found the actual printer problem.

4. Target a specific printer or class

When the same job number could exist on more than one destination, say which one you mean:

$ lprm -P PRINTER_NAME JOB_ID

Take the job ID and destination from the same queue listing; a class routes to one of several printers, so confirm cancelling the class job is really what you want.

For a remote server, -h comes before everything else:

$ lprm -h PRINT_SERVER:631 -P PRINTER_NAME JOB_ID

Use the host and port your print setup actually gave you, not a guess. Drop :631 if the server is on its default port. Re-run the matching query before and after cancelling if your environment lets you.

5. Keep identity and encryption deliberate

-U USERNAME asks the server to act as a different user:

$ lprm -U PRINT_OWNER -P PRINTER_NAME JOB_ID

Only use it when your setup expects that identity and you are actually authorised for it. Changing username changes which jobs count as "yours"; it is not a shortcut past access controls. Never put a password on the command line, in history, or in an example like this one.

-E forces encryption to the server, but only helps if the server and its certificate or auth setup support what you asked for:

$ lprm -E -h PRINT_SERVER:631 -P PRINTER_NAME JOB_ID

Encryption protects the connection. It does not select the right job and does not grant permission to cancel it. Elevated privilege is not a normal requirement here: sudo lprm ... changes which local identity gets presented and can select an entirely different set of jobs, so only use it when the print administrator has explicitly set that up.

Common traps

No arguments cancels the current job on the default destination:

$ lprm

That is not a harmless status check. Only run it once you already know what the current job is and actually want it gone.

A single hyphen cancels everything:

$ lprm -

That is destructive and service-disrupting, can hit other users' jobs, and has no batch undo. Never use it as a shortcut to find your own stuck job; recovering means resubmitting every document that was needed.

6. Diagnose a cancellation that did not stick

Compare the command against the queue listing first: destination spelling, job ID, server, then inspect again:

$ lpstat -o -P PRINTER_NAME
$ lprm -P PRINTER_NAME JOB_ID
$ lpstat -o -P PRINTER_NAME

If the job belongs to someone else, or the server rejects the request, do not jump to -U or sudo without confirming the access policy first. Ask the print administrator to remove it when your account is not authorised. If the job vanished between the two checks, another client or the scheduler probably beat you to it.

For a remote queue, repeat with the exact -h value you used to inspect it, still first in the options:

$ lprm -h PRINT_SERVER:PORT -P PRINTER_NAME JOB_ID

A successful cancellation does not mean the printer stopped instantly. It applies to the queued job; the printer may already have started or received the document before the server acted. If output has already reached the device, use the printer's own controls and your site's safety procedure.