python reportlab multipage pdf and custom fonts

When you need to generate a multi-page PDF in Python with a font that is not one of the built-in Helvetica, Times, or Courier families, ReportLab requires explicit font registration. The process is straightforward, but the details matter: you must register the font file, create a font object, and then attach it to paragraph styles. This article walks through the exact steps for python reportlab multipage pdf and custom fonts, including how to control page breaks and avoid common pitfalls with Unicode and font embedding.

Why ReportLab Needs Explicit Font Registration

ReportLab's default fonts are the standard PDF Type 1 fonts: Helvetica, Times-Roman, and Courier. These are always available and require no registration. For any other font, you must provide a TrueType or OpenType font file and register it with pdfmetrics.registerFont(). This is because PDF viewers expect fonts to be embedded or referenced correctly, and ReportLab does not assume you have access to system fonts. The registration step tells ReportLab where to find the font file and what name to use internally.

Without registration, attempting to use a custom font name in a paragraph style raises a KeyError or produces a fallback to a default font. The error is not always obvious; sometimes the text renders with the wrong font silently. So the first step is always to register the font before using it in any flowable.

Building a Minimal Multipage PDF with Platypus

Platypus (Page Layout and Typography Using Scripts) is ReportLab's high-level document builder. It manages page breaks, margins, and flowables automatically. The simplest way to create a multipage PDF is to use SimpleDocTemplate and pass a list of flowables like Paragraph and Spacer. Here is a minimal example that creates two pages:

from reportlab.lib.pagesizes import letter
from reportlab.lib.styles import getSampleStyleSheet
from reportlab.lib.units import inch
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak

doc = SimpleDocTemplate("example.pdf", pagesize=letter)
styles = getSampleStyleSheet()
story = []

for i in range(50):
    story.append(Paragraph(f"Paragraph {i+1}", styles["Normal"]))
    story.append(Spacer(1, 0.1 * inch))

# Force a page break after the first 25 paragraphs
story.insert(25, PageBreak())

doc.build(story)

This creates a two-page PDF because the PageBreak flowable forces a new page. Without it, ReportLab would automatically break pages when the content exceeds the page height. The automatic behavior is often sufficient, but explicit page breaks give you control over where content starts.

Registering Custom Fonts with TTFont

To use a custom font, you need a .ttf or .otf file. ReportLab's TTFont class handles both TrueType and OpenType fonts, though OpenType support depends on the font's internal tables. The registration code looks like this:

from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont

pdfmetrics.registerFont(TTFont("MyFont", "path/to/font.ttf"))

The first argument is the name you will use in styles. It can be any string, but it must match exactly when you set the fontName property. The second argument is the file path. Relative paths are resolved from the current working directory, so it is safer to use an absolute path or a path relative to the script's location.

For fonts that contain multiple weights (e.g., regular and bold), you register each weight separately with different names:

pdfmetrics.registerFont(TTFont("MyFont-Regular", "fonts/MyFont-Regular.ttf"))
pdfmetrics.registerFont(TTFont("MyFont-Bold", "fonts/MyFont-Bold.ttf"))

Then you can use MyFont-Regular and MyFont-Bold in different styles.

Applying Custom Fonts to Paragraph Styles

Once registered, you can create a custom ParagraphStyle that uses the font. The getSampleStyleSheet() provides default styles, but you can clone and modify them:

from reportlab.lib.styles import ParagraphStyle
from reportlab.lib.enums import TA_LEFT

custom_style = ParagraphStyle(
    name="CustomBody",
    fontName="MyFont-Regular",
    fontSize=12,
    leading=16,
    alignment=TA_LEFT,
)

Then use this style in your Paragraph flowables:

paragraph = Paragraph("This text uses a custom font.", custom_style)

If you need bold or italic, you must register the corresponding font files and create separate styles. ReportLab does not synthesize bold or italic from a regular font; it uses the exact font file you provide. So if you set fontName to a regular font and bold to True, the text will not appear bold unless you also set fontName to a bold variant.

Controlling Page Breaks in Long Documents

For a truly multipage PDF, you often need to control where pages break. ReportLab provides several flowables for this:

• PageBreak() forces a new page immediately.
• CondPageBreak(height) inserts a page break only if less than height space remains on the current page.
• Spacer adds vertical space and can influence natural breaks.

A common pattern is to use CondPageBreak to keep a section together. For example, if you have a heading and a paragraph that should stay on the same page, you can insert a CondPageBreak before the heading with a height equal to the heading plus the paragraph. This avoids orphaned headings.

from reportlab.platypus import CondPageBreak

# Reserve 2 inches for the heading and first paragraph
story.append(CondPageBreak(2 * inch))
story.append(Paragraph("Section Heading", heading_style))
story.append(Paragraph("Introductory text...", body_style))

For long documents with many sections, you can also use NextPageTemplate and PageTemplate to change page layouts, but that is more advanced. The basic PageBreak and CondPageBreak cover most needs.

Handling Unicode and Missing Glyphs

Custom fonts often include characters outside the Latin-1 range. ReportLab's TTFont supports Unicode, but the font file must contain the glyphs for the characters you use. If a glyph is missing, ReportLab will not raise an error; it will render a blank or a placeholder depending on the PDF viewer. To avoid this, test your content with the actual font and check for missing glyphs.

One common issue is with fonts that do not include a particular script (e.g., Cyrillic, Arabic, or CJK). You need a font that covers those code points. Also, some fonts have different internal encodings; ReportLab expects Unicode text, so you should ensure your strings are Python str objects (not bytes).

If you need to embed a font that is not licensed for embedding, ReportLab will still embed it, but you may violate the font's license. Check the font's license file before distributing the PDF. Some fonts allow only preview and print, not embedding. ReportLab does not enforce this; it is your responsibility.

Font Licensing and Embedding Constraints

PDF files can embed fonts in two ways: subsetting and full embedding. ReportLab by default embeds the entire font file. This increases the PDF size but guarantees the text renders correctly on any device. For large fonts, this can bloat the file. You can reduce the size by subsetting, but ReportLab does not provide a built-in subsetting option for TTFont. However, you can use external tools to create a subsetted font and register that instead.

Some commercial fonts have embedding restrictions. The font file's fsType field indicates the embedding permission. ReportLab does not read this field; it will embed regardless. To avoid legal issues, verify the font's license. For open-source fonts like those from Google Fonts, embedding is generally allowed.

Performance and Memory Considerations for Large PDFs

Generating a PDF with hundreds of pages and multiple custom fonts can consume significant memory. ReportLab builds the entire document in memory before writing it to disk. For very large documents, consider using canvas directly instead of Platypus, but that requires manual page management. Alternatively, you can generate the PDF in chunks by building multiple SimpleDocTemplate objects and merging them, but that adds complexity.

Font registration is a one-time cost. Once registered, each font is loaded into memory. If you use many fonts, memory usage increases. For a typical document with two or three fonts, this is negligible. If you are generating many PDFs in a loop, reuse the same registered font objects instead of re-registering them for each document.

Another performance factor is the number of flowables. Each Paragraph is laid out and wrapped, which is CPU-intensive. For long documents, consider using XPreformatted for pre-wrapped text or Table for structured data. But for most use cases, the straightforward Platypus approach is fast enough.

A practical tip: if you need to generate a PDF with a custom font that is not available on the target system, embedding is essential. ReportLab handles this automatically when you register the font. The resulting PDF will display correctly even on machines that do not have the font installed.

For a production system, you should also handle the case where the font file is missing. Wrap the registration in a try-except block and provide a fallback to a default font. This prevents the entire PDF generation from failing due to a missing asset.

try:
    pdfmetrics.registerFont(TTFont("MyFont", "fonts/MyFont.ttf"))
    font_name = "MyFont"
except (IOError, OSError):
    font_name = "Helvetica"

This pattern keeps your application robust when a font file is accidentally moved or not deployed.