Printing Problems on Linux (CUPS)

Most Linux distributions print through CUPS, the same printing system macOS is built on. When something goes wrong, the desktop settings may only say the printer is paused or a job failed, but CUPS has command-line tools and a local web interface that show exactly what's happening. This guide uses them to check the service, read printer status, revive stopped queues and set printers up with the right driver. Commands assume a typical desktop distribution and may need small adjustments on yours.

What you might be seeing

• The printer shows as paused, stopped or processing indefinitely
• Jobs fail with Filter failed or similar messages
• The printer isn't detected in the desktop printer settings
• Adding or changing printers fails with a permission error

Common causes

CUPS not running

If the scheduler service has stopped, nothing prints and desktop tools show no printers.

Queue stopped after an error

CUPS disables a printer after certain failures and leaves it disabled until it's re-enabled.

Missing or wrong driver

Printers without driverless support need the right driver or PPD, and filter errors often mean it's missing.

Permissions

Adding or changing printers requires membership of the printing admin group.

Discovery blocked

Network printers are found through the Avahi service, so if it's off or the firewall blocks mDNS, they won't appear.

How to fix it, step by step

Work through these in order and test a print after each one. Most people are done within the first few steps.

1. Check that CUPS is running

   Open a terminal and run systemctl status cups, looking for active (running) in the output. If it's inactive or failed, run sudo systemctl restart cups and check again, and run sudo systemctl enable cups so it starts at boot. Service names differ slightly on a few distributions, so check your distribution's documentation if cups isn't found.

2. Read printer status with lpstat

   Run lpstat -p -d to list each printer, whether it's idle, printing or disabled, and which is the default. lpstat -o lists waiting jobs, and lpstat -t shows everything at once, including the device each printer uses. A printer marked disabled with a reason, or a long list of old jobs, tells you where to look next.

3. Re-enable a stopped printer

   If lpstat shows a printer as disabled, run sudo cupsenable PRINTERNAME, using the exact name from the lpstat output. If it's also rejecting jobs, run sudo cupsaccept PRINTERNAME too. To clear stuck jobs first, cancel -a PRINTERNAME removes every job for that printer. Then send a quick test with echo test | lp -d PRINTERNAME and watch the status again.

4. Use the CUPS web interface

   Open a browser and go to localhost:631, the CUPS interface running on your own computer. The Printers tab lists every queue with its state and recent errors, and each printer's page has menus to resume it, cancel jobs or print a test page. The Administration tab adds and modifies printers, asking for your own user name and password.

5. Give your account printing admin rights

   If you can't add or change printers, your account may lack permission. On Debian, Ubuntu and related systems, run sudo usermod -aG lpadmin $USER, then log out and back in. Other distributions use a different admin group, such as wheel or sys; the SystemGroup line in /etc/cups/cups-files.conf shows which groups CUPS accepts.

6. Add the printer as a driverless device

   Most current network printers support IPP Everywhere, which needs no driver. Run sudo lpinfo -v to list detected devices and look for an entry starting with ipp or ipps. Add it in your desktop's printer settings or the web interface, choosing the IPP Everywhere or driverless option as the model. From a terminal, sudo lpadmin -p Office -E -v DEVICE -m everywhere does the same, with DEVICE replaced by the address lpinfo printed.

7. Install drivers for older printers

   Printers without driverless support need a driver package. Search your distribution's software manager or package manager for printer driver packages, which cover many older models, or download the official Linux driver from the manufacturer's website if one is offered. Then add the printer again and choose your exact model. Persistent filter errors usually mean the selected driver doesn't suit the printer.

8. Check discovery and read the logs

   If network printers don't appear automatically, run systemctl status avahi-daemon and start it if needed. If you use a firewall, allow the mDNS and IPP services through it rather than turning the firewall off. For deeper problems, journalctl -u cups or the file /var/log/cups/error_log shows detailed errors, and sudo cupsctl --debug-logging adds more until you run sudo cupsctl --no-debug-logging.

How to keep it from happening again

• Prefer driverless IPP Everywhere setups for network printers
• Keep CUPS and driver packages current through system updates
• Use a reserved IP address for network printer queues
• Remove queues for printers you no longer use