Set and Verify CUPS Printer Defaults with lpoptions

Every job printed on the wrong paper size is a saved default nobody checked, and lpoptions fixes that. You will inspect a CUPS printer, set a default option for your user, create a reusable printer instance, and undo those saved settings without removing the printer queue. Allow about ten minutes if you already know the queue name. The examples assume a shell and a CUPS client, not a particular printer model.

1. Check the installed client and printer names

This machine has cups-client version 2.4.7 installed. The local manual page is the reference for the commands in this guide. You need a destination, also called a queue, before printer-specific options can be listed or saved.

$ command -v lpoptions
/usr/bin/lpoptions
$ dpkg-query -W -f='${Package} ${Version}\n' cups-client
cups-client 2.4.7-1.2ubuntu7.14
$ lpstat -p -d
printer OFFICE_QUEUE is idle.  enabled since ...
system default destination: OFFICE_QUEUE

Replace OFFICE_QUEUE below with the exact name printed by lpstat. Output and the available options are printer-specific. On a machine with no queues, the final command instead reports lpstat: No destinations or a similar local error; add or discover a queue through your normal CUPS administration process before continuing.

Checkpoint: set a shell variable to the queue name, then display its current saved options. This only reads configuration:

$ PRINTER_NAME='OFFICE_QUEUE'
$ lpoptions -p "$PRINTER_NAME"
copies=1 device-uri=ipp://printer.example/ipp/print finishings=3 media=A4 ...

The output is host-specific. If there are no saved options, it may be empty or contain only values supplied by CUPS. Do not treat this output as a list of every capability the printer supports.

2. List the options that this printer supports

Use -l with -p to ask CUPS for printer-specific options and their current settings:

$ lpoptions -p "$PRINTER_NAME" -l
PageSize/Media Size: A4 *Letter Legal
Duplex/Two-Sided: None *DuplexNoTumble DuplexTumble
ColorModel/Colour Model: Gray *RGB

The exact names, labels and values depend on the queue and its printer description. An asterisk marks the current value in the usual CUPS listing. Copy the option name and value as shown, rather than guessing a spelling such as duplex=true: a queue can expose an option under a different name, or not expose a feature at all.

A normal user can run this command. It contacts the CUPS server but does not submit a job or change the queue.

3. Save one default option for your user

After checking the list, use -o to save an option for the named destination:

$ lpoptions -p "$PRINTER_NAME" -o media=A4
$ lpoptions -p "$PRINTER_NAME"
media=A4 ...

This changes your saved CUPS preferences. For a non-root user, lpoptions manages ~/.cups/lpoptions. The setting is used by lp and lpr when they submit jobs for this user. It does not alter the printer queue, reload a service or print anything.

Use the exact value reported by -l. For example, if the listing calls the feature sides, the command might be lpoptions -p "$PRINTER_NAME" -o sides=two-sided-long-edge. The value is not universal: the available choices belong to the queue.

To check which destination an ordinary print command will choose, inspect the CUPS defaults as well as your shell environment:

$ printf 'LPDEST=%s PRINTER=%s\n' "${LPDEST-}" "${PRINTER-}"
LPDEST= PRINTER=
$ lpoptions
media=A4 ...

With no -p, lpoptions uses the default printer. CUPS also considers the LPDEST and PRINTER environment variables when commands such as lp choose a destination, so a shell environment can make a test use a different queue than you expect. Clear or inspect those variables before diagnosing a surprising result.

4. Create a named instance for a repeatable setup

An instance is a saved set of options associated with a queue, written as QUEUE/INSTANCE. It does not create a new printer destination. This example creates a separate double-sided instance:

$ INSTANCE_NAME="${PRINTER_NAME}/duplex"
$ lpoptions -p "$INSTANCE_NAME" -o sides=two-sided-long-edge
$ lpoptions -p "$INSTANCE_NAME"
sides=two-sided-long-edge ...

If the instance does not exist, lpoptions creates it in your per-user options file. The main queue and the instance have separate saved options: do not assume that an option saved on the main queue will be inherited by an instance.

When you want to use the instance, pass its complete name to a print command, for example:

$ lp -d "$INSTANCE_NAME" /path/to/document.pdf
request id is OFFICE_QUEUE-42 (1 file(s))

This last command submits a real print job. Check the destination, file and paper settings before running it. If the document should not be printed yet, stop after verifying the instance with lpoptions; no job is created by that check.

5. Remove a saved option or instance

Warning: the next commands change saved configuration. They do not delete the queue, but removing the wrong option can change later print jobs for your user. Record the current output of lpoptions first if you may need to restore it.

Remove one option from a destination with -r:

$ lpoptions -p "$PRINTER_NAME" -r media
$ lpoptions -p "$PRINTER_NAME"
... media is no longer listed as a saved option

Recovery: the exact remaining output varies, and a default can still come from the queue or CUPS rather than your user file. To restore the setting, use the value from the printer's -l output again, for example lpoptions -p "$PRINTER_NAME" -o media=A4.

To remove all saved options for an instance, use -x with the complete instance name:

$ lpoptions -x "$INSTANCE_NAME"
$ lpoptions -p "$INSTANCE_NAME"
lpoptions: ...

The instance is no longer useful as a saved configuration after this operation, though the queue itself remains present. If the instance name did not exist, -x does nothing. To recreate it, repeat the command from step 4. Do not use lpadmin merely to undo an lpoptions change: queue creation and removal belong to the administrator tool.

6. Understand user and system scope

Run the examples as the user who will print. A non-root invocation writes per-user defaults and instances to ~/.cups/lpoptions. Running lpoptions as root changes defaults and instances in /etc/cups/lpoptions for all users. That is an administrative change, so do not add sudo just because a printer option looks system-wide.

If a site administrator deliberately needs a global default, verify the queue and option values first, schedule the change if it affects other users, and keep a copy of the existing file before editing it. The lpoptions command itself is preferable to hand-editing the file because it applies the documented destination and instance syntax. No elevated privilege is needed for inspection or for a user's own settings.

7. Use another CUPS server when required

The -h option selects an alternate server and must appear before the other options. Add -E when the CUPS connection must use encryption:

$ lpoptions -h print.example:631 -E -p "$PRINTER_NAME" -l
PageSize/Media Size: A4 *Letter Legal
...

Substitute the server and queue supplied by your administrator. This command may require server authentication or access that your local account does not have. Do not put passwords in the command line or in shell history. If the server name, port or queue is wrong, fix that first rather than changing local defaults.

Done means