CUPS Command-line Tools

General information on the command-line tools: 

  • Do not edit the configuration files in /etc/cups/ manually if suitable command-line tools are available for this purpose.


The configuration files are not reloaded for every print job. Rather, cupsd keeps much of the information in the main memory and writes information back to the configuration files whenever needed. Exception: /etc/cups/cupsd.conf

After modifications in this configuration file, cupsd must be restarted in order to make it use the modified configuration. See Section "Restarting the CUPS Server" in the "CUPS Software Administrators Manual" http://localhost:631/sam.html#RESTARTING or file:///usr/share/doc/packages/cups/sam.html#RESTARTING.

  • Never copy configuration files from other systems to your system unless you know exactly what you are doing. Use command-line tools instead.

For example, to set up the same queues on several machines (e.g., for a backup server), do not copy /etc/cups/printers.conf and /etc/cups/ppd/*, but write the respective commands in a script (usually a sequence of lpadmin commands) and run the script on the various machines. In this way, any error messages will be displayed on the respective machines (e.g., if a PPD file is not available on a machine or if a backend is not available or not ready to use). Furthermore with such a script you have something like a log-file of the settings, enabling you to restore the settings by running the script at any time.

  • If you are not sure which graphical tool is best suited for certain special configurations, use command-line tools instead.
  • In many cases, the sequence of the options is significant. Read the man pages. For example, the following commands are all different:

    lpadmin -E -p queue,
    lpadmin -p queue -E
    lpadmin -E -p queue -E


Command-line tools for creating or editing queues:

  • Example for creating a queue:

    root@host# lpadmin -p funprinter1000 -v parallel:/dev/lp0 -E -P /usr/share/cups/model/Postscript.ppd.gz

Use the following command to check what was created:

user@host$ lpstat -a funprinter1000 -p funprinter1000 -v funprinter1000
funprinter1000 accepting requests since Jan 01 00:00
printer funprinter1000 is idle.  enabled since Jan 01 00:00
device for funprinter1000: parallel:/dev/lp0

Alternatively, take a look at /etc/cups/printers.conf:

<Printer funprinter1000>
Info funprinter1000
DeviceURI parallel:/dev/lp0
State Idle
Accepting Yes
JobSheets none none
QuotaPeriod 0
PageLimit 0
KLimit 0

Or query the system with the web front-end: http://localhost:631/printers/funprinter1000

  • Editing the queue (e.g., changing the description and location):

    root@host# lpadmin -p funprinter1000 -D "ACME FunPrinter 1000" -L "2. floor: room 3"
  • Displaying the printer-specific options and their default settings in /etc/cups/ppd/funprinter1000.ppd:

    user@host$ lpoptions -p funprinter1000 -l
    Resolution/Output Resolution: 150dpi *300dpi 600dpi 1200dpi 2400dpi
    PageSize/Media Size: Letter Legal Executive *A4 A5

The output has the following syntax:

main-keyword/translation-string: option-keyword option-keyword option-keyword ...

The default setting is marked with an * preceding the "option-keyword".

  • Changing the printer-specific default settings in /etc/cups/ppd/funprinter1000.ppd:

    root@host# lpadmin -p funprinter1000 -o Resolution=600dpi -o PageSize=Letter

The syntax is as follows:

lpadmin -p queue -o main-keyword1=option-keyword1 -o main-keyword2=option-keyword2 ...

Do not use lpoptions for this purpose. Refer to the Support Database article "Print Settings with CUPS": SDB:Print Settings with CUPS. Normal users can use lpoptions to save their personal default settings in ~/.lpoptions. More information on this is presented in the same Support Database article.

  • Use "accept" and "reject" to accept and reject print jobs for a queue. Use "/usr/bin/enable" ("enable" is a bash built-in) and "disable" to enable and disable printing in a queue (e.g., to avoid print jobs from being lost while doing maintenance work on the printer).
  • Deleting the queue:

    root@host# lpadmin -x funprinter1000

Command-line tools for daily use

  • Avoid BSD-type commands (lpr, lpq, lprm), as these only support a limited number of generic options. Use System V-type commands (lp, lpstat, cancel) instead.
  • Use lpoptions to save personal printer-specific option settings in ~/.lpoptions. Example:

    user@host$ lpoptions -o Resolution=1200dpi -p funprinter1000
  • The generally available printing options are described in the Section "Standard Printer Options" in the "CUPS Software Users Manual": http://localhost:631/sum.html#STANDARD_OPTIONS or file:///usr/share/doc/packages/cups/sum.html#STANDARD_OPTIONS

documented on: 2006.09.07