Help

The Prince User Guide tries to be exhaustive in explaining how to use the application and its features. However, there might always be something not answered in the documentation, or something not working as expected. There are a couple of ways to get help to solve the problems:

The Troubleshooting section addresses possible common issues after installing and starting to use Prince;
The Frequently Asked Questions section provides answers to the most frequently asked questions;
The forum is an excellent place where to find an answer to an issue, or where to ask for help;
You can contact us for support.

Troubleshooting

We work hard to make Prince work on multiple platforms (Windows, Linux, etc) and with multiple configurations. However things don't always work correctly the first time. You're very welcome to contact us for support or visit our forum. However if you are facing a common problem, you may be able to find an explanation and solution below.

Output log

When running into trouble with Prince, the first thing you should do is to check for any errors. These can be found in the Prince output log.

When launching Prince from the command line, Prince will print any error or warning messages directly to the console, prefixed with error: or warning: messages. The level of verbosity, or a log file where to print all output, can be controlled with a few command-line Logging Options. A more advanced control of the output is given by the Structured Log.

When using the Prince GUI, the output log is printed to the log window on the bottom left of the main GUI window.

Image formats

Symptom

    prince: ./picture.bmp: warning: Unknown image format

Explanation
Prince supports the JPEG, PNG, TIFF, GIF, WebP and AVIF image formats, as well as SVG (see Images). If you try to format a document that includes images in a format that is not supported by Prince, such as BMP, you may see the above error message from Prince.

Solution
The solution is to convert the image file into a format that is supported by Prince. We suggest PNG, which is a well-supported general purpose image format with lossless compression.

The capture/replay system

Prince offers a convenient capture/replay system with the two command-line options --capture and --replay - the former saving a copy of all the information in a job to a specified directory, including the input document(s) and all of the resources referenced by them and on the command line (including remote HTTP resources), such as style sheets, images, JavaScript files, fonts, etc., conveniently allowing it to be replayed later for debugging purposes with the latter command-line option. The directory might contain sensitive information (as far as included in the PDF job), so we recommend only submitting them by email when requested to do so, instead of posting them on the forum.

Running the debug script

For assisting in tracking down difficult platform bugs, the princedebug script is available on Linux and MacOS platforms. It is located in /usr/lib/prince/bin and runs Prince with the specified command-line arguments, dumping a considerable amount of debug information to two files in the /tmp directory, namely prince.debug and prince.strace.

These files contain information about the system and environment in which Prince was run, and about the job in question, so we recommend only submitting them by email when requested to do so, instead of posting them on the forum.

This script is not available on Windows.

Frequently Asked Questions

Why do I see garbled characters on my page?

This usually happens when Prince is not able to find a suitable font, or might be using the wrong font. Try installing a font that supports your script, or try using a different font in your stylesheet. See also: Fonts and Redefining the generic font families.

Why do I get strangely misspelled words when I copy text from the PDF?

Prince creates artificial bold text by double printing with an offset when it does not find a bold font. To solve the issue, install the bold font, or try running Prince with the command-line option --no-artificial-fonts. See also Defining a font family.

Why is all the content displayed on one page, while I was expecting it to take several pages?

Typically content displays on only one page, even though it should be much longer, because it is wrapped up:

in an absolutely positioned element, or
in a floated block element, or
in a single inline-block element, or
in an element with fixed height, or
in an element with overflow: hidden,

which Prince cannot split over several pages. It can happen to the whole content in a document, or to just a section of it. This issue does not affect browsers, because they don't paginate. See also: Paged Media.

How can I resize my web page to fit it on the printed page?

Prince usually takes care of reformatting a document to fit on a printed page. However, there are cases where it doesn't work as expected.

Wide content can be made to fit by Rotating content, or by applying the CSS property -prince-shrink-to-fit, which scales down all content equally. Alternatively, the command-line option --css-dpi changes the DPI of the "px" units in CSS, which defaults to 96dpi.

We do not recommend people making a habit of using this, and instead advise to design a layout specifically appropriate for the paper being used. Or at least using relative size units.

Note that this however does not affect tall content - if you need elements too tall to fit on a page to be rescaled, there are other ways of achieving this: e.g. by limiting the max-height of an element - Prince supports Viewport Length Units, and in a paged media context the viewport units refer to various aspects of the page and page area.

Alternatively, Flex Layout can be used, or the content can be custom resized with The Box Tracking API.

Why does my PDF file not show the transparent background?

Different PDF profiles have different requirements - you might be generating a PDF with a version or profile which does not support transparency. The only PDF profile to support transparency is the PDF/X-4 profile. See also: PDF Versions and Profiles and Color Management and PDF Profiles.

How can I create tooltips in the PDF file?

PDF tooltips can be enabled with the CSS property -prince-tooltip like this:

    *[title] { -prince-tooltip: attr(title) }

However, please note that tooltips are not a standard PDF feature, and they may only work in Adobe Reader and Adobe Acrobat and may not be visible in other PDF viewers, such as web browsers.

How can I make an element, such as an image or some text, appear on each page of the PDF document?

For this purpose you can use the @page page regions. See: Page regions and Watermarks.

How can I apply CSS styles in page regions?

You cannot add style to generated content in the page regions, except for some inline style properties, such as color and font. A possibility for using more complex styling is to use the element() or flow() CSS functions. See Generated content in page regions, Copying content from the document and Taking elements from the document - however, this latter approach will remove the element from the document itself.

How can I start counting pages on a left page and display a right page as second page?

You can specify break-before:left | right on the root element of the document.

CSS

    body[start=even] {
      break-before:left;
    }

HTML

    <body start="even" startpage="28">

Does Prince support JavaScript?

Yes, Prince supports JavaScript - remember to enable it with the --javascript command-line option (see Applying JavaScript in Prince). However, there are some limitations: Prince produces printed documents, and interactive events make no sense in this context. Also, modifications of the document after layout has finished are not possible. See: Scripting.

Can I modify the document after layout has finished?

Part of the inherent limitations of printed media is the impossibility to modify a document after it has been printed - see JavaScript in Printed Media.

However, Prince offers the possibility to register the function Prince.registerPostLayoutFunc(func) after layout has finished and before producing the PDF for possibly triggering a new layout - see Multi-Pass formatting for more details.

Why are Web fonts not loaded?

Prince supports and loads web fonts. However, in some specific cases the web fonts served to Prince might differ from those served to browsers. In such cases the command-line options --user-agent may be used to spoof the user agent string sent to the servers, basically pretending to be a browser.

Please be aware that there can be unforseen side-effects when pretending to be somebody else on the web.

Can I include content of external files in my document?

Yes. In XML, this is done by means of XML Inclusions (XInclude). Note that XInclude is disabled by default, and can be enabled with the --xinclude command-line option. Also note that XInclude only applies to XML files.

To apply it to HTML files, the XML input format needs to be specified with the --input command-line option.

Another option in HTML is to use the iframe element:

    <style>
    @page {
      @bottom {
        border: solid red thin;
        content: flow(footer)
      }
    }
    .footer {
      flow: static(footer)
    }
    </style>
    <iframe class="footer" src="https://www.google.com"></iframe>
    <p>Normal content</p>

However there may be some subtleties required to get the correct size and styling of content within iframe elements.

Yet another option would be to use JavaScript to issue an XMLHttpRequest, parse the text of the response with DOMParser, then extract the elements and copy them into the main document. However, it will be tricky to support nested styles this way.

CSS Support

Miscellaneous