Printing without tears

Performing a CUPS reset through the Printers & Scanners pane.

Like anti-lock brakes and conception, most of the time printing just works fine, however it works. But when it doesn’t, understanding how documents are printed become crucial.

However committed you are to doing without paper, there comes a time when you have to put it in writing. Whether you feed your printer with paper daily, or dig it out occasionally, what emerges in print is not always what you had intended. As with all complex sequential processes, unless you understand how they work, you will be hard pressed to work out where they fail, and how to fix them.

Spooling to PDF

Normally, when you open a document and it is displayed in a window, the application reads the data that form the document, works out which content needs to be displayed in the current view, then draws that content using standard calls to graphics functions in OS X. For example, this might include a paragraph of text to be laid out in a particular font and size, below which is an image.

When you tell that application to print the document, it opens a temporary spool file, and renders the document into that in PDF. Stepping through one page at a time, the application uses the same drawing commands as if it was rendering the page to the display, but this time its ‘virtual display’ is the PDF spool file. A print job ticket is also created, and associated with that spool file.

When this works properly, it means that printing is just like the screen display, and truly WYSIWYG. You can of course intercept that spool file and check it, either by using the Print Preview command if that is available, or by making the PDF file the final output, clicking on the PDF button at the bottom left of the Print dialog, and selecting the Save as PDF… option.

When printing is working correctly, there should be no difference at all between what you see on screen in the application, what you see in the PDF preview or output file, and what appears on paper.

If there are differences between on-screen and PDF rendering, these are normally issues arising in the application itself, or possibly in OS X. If you can open that document using a different application, it may be able to work around bugs in the original application, and print the document correctly.

This was the case, for example, with a serious bug in some older versions of Adobe Acrobat Pro that superimposed a red layer over page contents in certain circumstances: the red layer did not appear when Preview was used instead. This was particularly puzzling, as the work required to render a file that is already in PDF format into a PDF spool file is relatively trivial.

Sometimes you can work around bugs in creating PDF spool files by saving as PostScript instead, from the PDF button in the Print dialog. PostScript output can be turned into PDF by Adobe Acrobat Distiller, which could turn out to be a means of printing a document that would otherwise appear flawed.

Sending the PDF to the printer

The PDF spool file and its associated job ticket are handed over to the print server that is built into OS X, CUPS (Common Unix Printing System). The latest release of CUPS, built into OS X 10.10.3, is 2.0.0 (although the general release no-OS X version is now 2.0.2).

This is normally the stage at which the background Print app fires up, showing the list of jobs queued to go out to the printer. CUPS then calls on the printer software to convert the PDF spool file into whatever form the printer needs, and to communicate with the printer, so that the job can be sent out to it.

CUPS has its own web interface, but in Yosemite you will need to enable it first by entering the following command in Terminal’s command line:
cupsctl WebInterface=yes
Once that is done, you can inspect CUPS by pointing your normal browser at localhost:631/

This not only opens up pages offering detailed configuration and detailed listing of active and completed jobs, but has a wealth of documentation, supplemented by its website. Most printing problems arise between CUPS and the printer itself, as revealed by preview PDFs that are correct but output that is flawed or never appears, and are often down to the printer driver.


Printer drivers have two tasks: first to convert the PDF spool file into a stream of data that the printer can turn into output pages, and second to handle communications with the printer, and control over output of the data stream. Conversion from PDF is simplest for the two extremes of printer: old devices that have no support for page description languages, and modern devices with built-in PostScript interpreters (or emulators).

The oldest printers required drivers that rendered a virtual pixel map image of each page, and simply controlled the print engine to lay those pixels down on the paper. At the other extreme, a printer with a good PostScript interpreter merely requires the driver to translate from PDF – a subset of PostScript – into full-blown PostScript, which its processor then renders to the print engine.

In either case the driver may not handle the printer’s processor correctly, for example sending it duff code that generates an error in a PostScript interpreter, or sending too much data and causing the printer’s memory to overflow. Such driver-printer errors should be returned to CUPS, or you can set options to print a detailed error report to aid your diagnostics.

Unfortunately errors reported back from the printer tend to be both opaque and very hard to address. One common report, of a PostScript stack overflow, indicates that the data sent to the printer has resulted in an error condition in its PostScript interpreter, but that could be the result of a flawed object on the page, a bug in the printer driver, or a fault or limitation in the print engine.

Other than trying to simplify the page by removing important content from it, and trying again, there is usually little that the user can do to further diagnose or fix such problems.

Printer connections

Communications with the printer are another area that can cause you grief. Local printers attached to a USB port are usually simplest, and provided they are correctly connected should work fine. Networked printers, or USB printers that are being shared over the network, are vulnerable to almost any problem that can afflict networked devices, from duff cables to duplicate IP addresses.

As you cannot ping from your printer to your computer, diagnosing network printer problems is like wrestling with one arm tied behind your back.

Printer errors

The final class of printer errors is those perpetrated by the printer itself: the PDF spool file is fine, CUPS has handled the job correctly, and the driver has done its work well, but the print engine or printer mechanism has let you down.

In many cases, such as streaking, blotching, and other physical flaws, the cause is obvious. However colour casts and more subtle issues could arise at any step in the process. Most printers offer cleaning, calibration, and test page facilities that can be accessed from your Mac, or the printer controls themselves, that should help you pin down which step is responsible.

Work systematically and logically, and armed with this clear understanding of the steps involved in printing, you should be able to figure out what is going wrong, and perhaps how you can try to fix it.

Techniques: Generic Printer Troubleshooting

If you are unsure where to start, or the clues do not point to a clear cause of a printing problem, first check your printer connection, cable, that it is powered on, and has sufficient supplies including paper.

Then open the App Store’s Updates pane (or Software Update pane in System Preferences), and check for any relevant updates, such as new printing software. When your printer is properly installed, any updates to its drivers should be offered automatically to you in the App Store if they are provided through Apple. For printers that are supported by downloads direct from their vendor, check their website for latest updates.

Having made sure that everything appears to be in fine fettle, open the Printers & Scanners pane, select the printer from the list, and click on the – tool to remove it. Once it has disappeared from there, click on the + tool and add the printer back, reconfiguring it carefully.

A typical printer web interface page for a networked printer.
A typical printer web interface page for a networked printer.

If the manufacturer provides a separate utility from its website, try downloading, installing, and running that, as it may give you fuller diagnostic information. Networked printers are also usually accessible via a browser interface, which should be documented. For instance, a printer with Bonjour support might be accessed by pointing your browser at http://npi8f278c.local./, where ‘npi8f278c’ is the designated printer host name.

Custom printer web interface pages usually give ample detail on toner levels.
Custom printer web interface pages usually give ample detail on toner levels.
Performing a CUPS reset through the Printers & Scanners pane.
Performing a CUPS reset through the Printers & Scanners pane.

You may also find it helpful to reset the printing system (CUPS), which deletes all print queues and jobs, resets all printer settings to their default by trashing configuration files, and checks permissions on the hidden /tmp folder used to store print jobs. To do this, open the Printers & Scanners pane and select the printer concerned. Then bring up the contextual (popup) menu by Control-clicking (etc.), and select the menu command to reset the system.

Tools: CUPS and More

Few ever need to access CUPS or the command line tools that support the printing system directly, but sometimes they can work around problems like nothing else.

First ensure that the CUPS web interface is enabled by typing
cupsctl WebInterface=yes
in the command line of Terminal.

cups1Then point your browser at localhost:631/ the CUPS front page. This shows the version running on your Mac, which – if you are running the latest release of OS X – should tally with the last full release listed at Although there is no fundamental reason that you could not update CUPS independently of OS X, because it depends on other components in OS X, this is likely to cause a succession of problems.

Click on the Command-line Printing and Options item to see details of shell tools that you can use in Terminal, or shell scripts. The basic printing tools are lp and lpr, whose rich command structure and options can also be viewed by typing man lp or man lpr into Terminal. Click on the Jobs tab at the top of the CUPS page to see its jobs log; this not only shows currently active print jobs, but recently completed jobs listed by ticket number.

CUPS administration tools, accessed through it web interface.
CUPS administration tools, accessed through it web interface.

The Administration tab gives access to powerful admin controls, including extensive customisation of the drivers and other options for each printer. These can also be reached through individual device details provided by the Printers tab. Command line tools lpstat and lpoptions, documented in the CUPS pages and their own man pages in Terminal, provide an alternative interface.

CUPS printer page, listing all currently-installed printers.
CUPS printer page, listing all currently-installed printers.

OS X has other tools for printing that can prove useful if you are prepared to get to grips with the complexity of their options. Notable among these is the shell command enscript, which can format plain text output in a myriad of different ways. Such raw power may be best wrapped up with a friendly AppleScript front end.

Updated from the original, which was first published in MacUser volume 28 issue 18, 2012.