gopdf: A Go Library for Generating PDFs with TTF Fonts, Shapes, and Password Protection

What gopdf Generates and Who Uses It

gopdf generates PDF files entirely in Go, without calling an external rendering engine or a headless browser. It targets backend services that need to produce invoices, reports, certificates, or other documents programmatically.

The library handles Unicode text with subfont embedding, which means it can write Chinese, Japanese, and Korean characters correctly by embedding only the glyphs that appear in the document. It also draws vector shapes, embeds raster images, applies password protection, and can import pages from existing PDF files.

The Coordinate-Based API and Printing Text

gopdf uses a coordinate-based approach. Every text and image placement is positioned by X/Y values on the page. The first step for any document is to start the configuration and add a page:

pdf := gopdf.GoPdf{}
pdf.Start(gopdf.Config{ PageSize: *gopdf.PageSizeA4 })
pdf.AddPage()

Text requires a TTF font loaded by path, then set as the current font:

err := pdf.AddTTFFont("wts11", "../ttf/wts11.ttf")
if err != nil {
    log.Print(err.Error())
    return
}
err = pdf.SetFont("wts11", "", 14)

After that, `pdf.Cell(nil, "您好")` places text at the current cursor position. The document is written to disk with `pdf.WritePdf("hello.pdf")`. The font name registered with `AddTTFFont` is local to the document; the string `"wts11"` is just the key used later in `SetFont`.

For aligned or wrapped text, `CellWithOption` and `MultiCellWithOption` take a `CellOption` struct. Justify alignment stretches a single line to the full cell width. In a paragraph, every line is justified except the last, which stays left-aligned. Lines that already fill or overflow the cell are left-aligned unchanged.

Drawing Shapes and Placing Images

gopdf draws lines, ovals, polygons, and rectangles. Line style and width are set before drawing:

pdf.SetLineWidth(2)
pdf.SetLineType("dashed")
pdf.Line(10, 30, 585, 30)

Polygons take a slice of `Point` values and a fill/stroke mode string:

pdf.SetStrokeColor(255, 0, 0)
pdf.SetFillColor(0, 255, 0)
pdf.Polygon([]gopdf.Point{{X: 10, Y: 30}, {X: 585, Y: 200}, {X: 585, Y: 250}}, "DF")

Rounded rectangles are drawn with `Rectangle`, which takes the corner radius and a segment count:

err := pdf.Rectangle(196.6, 336.8, 398.3, 379.3, "DF", 3, 10)

Images are placed by file path with X/Y coordinates:

pdf.Image("../imgs/gopher.jpg", 200, 50, nil)

JPEG and PNG are supported. Image masking is listed in the feature set. Text and images can be rotated:

pdf.SetXY(100, 100)
pdf.Rotate(270.0, 100.0, 100.0)
pdf.Text("Hello...")
pdf.RotateReset()

Color Models, Transparency, and Superscript

gopdf supports both RGB and CMYK color models for text, stroke, and fill. RGB colors are set with three integer values:

pdf.SetTextColor(156, 197, 140)

CMYK colors use four channel values:

pdf.SetTextColorCMYK(0, 6, 14, 0)

The CMYK model is relevant for documents intended for print production, where color fidelity under different ink profiles matters.

Transparency is set through a `Transparency` struct with an `Alpha` value between 0 and 1 and an optional `BlendModeType`. The README points to Adobe's PDF 32000:2008 specification for the full list of blend modes.

Superscript and subscript use `SetFontWithStyle` with the `gopdf.Superscript` or `gopdf.Subscript` constants. The glyph size and baseline shift come from the font's own metrics:

pdf.SetFont("font", "", 14)
pdf.Cell(nil, "E = mc")
pdf.SetFontWithStyle("font", gopdf.Superscript, 14)
pdf.Cell(nil, "2")
pdf.SetFontWithStyle("font", gopdf.Regular, 14)

Links, Headers, Footers, and Font Kerning

gopdf supports both external and internal links. External links bind a URL to a rectangular region on the page. Internal links use named anchors for navigation within the document:

pdf.Text("Link to example.com")
pdf.AddExternalLink("http://example.com/", 27.5, 28, 125, 15)

pdf.Text("Link to second page")
pdf.AddInternalLink("anchor", 27.5, 58, 120, 15)

The `AddExternalLink` and `AddInternalLink` calls each take X, Y, width, and height to define the clickable region. This allows links to be placed over text or images without changing the visible content.

Headers and footers are registered as functions that run on each page. The approach uses callbacks rather than templates:

pdf.AddHeader(func() {
    pdf.SetY(5)
    pdf.Cell(nil, "header")
})
pdf.AddFooter(func() {
    pdf.SetY(825)
    pdf.Cell(nil, "footer")
})

This means the header and footer logic has full access to the gopdf API. A header can draw a logo image, a rule line, and a text label in a single callback.

Font kerning is listed as a supported feature. Kerning adjusts the spacing between specific letter pairs according to the font's built-in kerning table, which affects the visual rhythm of headlines and large display text more than body text.

Password Protection and Importing Existing PDFs

Password protection is configured at startup through `PDFProtectionConfig`. Owner and user passwords are set as byte slices, and permissions are composed with bitwise flags:

pdf.Start(gopdf.Config{
    PageSize: *gopdf.PageSizeA4,
    Protection: gopdf.PDFProtectionConfig{
        UseProtection: true,
        Permissions: gopdf.PermissionsPrint | gopdf.PermissionsCopy | gopdf.PermissionsModify,
        OwnerPass:   []byte("123456"),
        UserPass:    []byte("123456789")},
})

Importing existing PDF pages is powered by the gofpdi package, which gopdf lists as a dependency in go.mod. This lets gopdf use an existing PDF as a template or background by importing its pages before adding new content.

Limitations of the Coordinate-Based Approach

Every text and image placement in gopdf requires explicit X/Y coordinates. There is no automatic text flow between columns, no automatic page break when content overflows, and no built-in table layout system. Building a multi-page report with dynamic content lengths requires the developer to track the current Y position and add new pages manually.

The library supports only TTF fonts. OpenType fonts with CFF outlines are not mentioned. The standard library in go.mod has one dependency: gofpdi at a specific pre-release commit hash, which is not a tagged release. This means the full dependency chain is locked to that specific snapshot.

The README states that a minimum of Go 1.13 is required, but does not document which PDF specification version the library targets.

The repository's top-level directory contains separate Go source files for each rendering operation: `cache_content_line.go`, `cache_content_image.go`, `cache_content_rotate.go`, `cache_content_text.go`, and similar. This structure means the library is not a single monolithic file, but it also means there is no public API documentation beyond the README examples and in-repository test files. Engineers who need a feature not shown in the examples will need to read the source to understand the full call signatures.

The examples directory covers Arabic text, clip-polygon, mask-image, mask-with-rotated-image, outline, and table use cases. The Arabic helper files (`arabic_alphabet.go`, `arabic_helper.go`) indicate the library handles right-to-left Arabic text, though this feature is not listed in the README's feature summary.

How gopdf Compares to unipdf

unipdf (formerly known as unidoc) is a Go PDF library that covers both generation and parsing, supports digital signatures, form filling, and advanced PDF features aligned with the PDF 2.0 specification. unipdf is a commercial product with a paid license for most production uses.

gopdf is MIT-licensed and has no commercial licensing requirement. Its feature set is narrower: it generates PDFs and can import pages, but it does not fill forms, sign documents, or expose a full PDF object model for parsing. For applications that need only generation with TTF fonts and basic shapes, gopdf is a straightforward choice that avoids licensing overhead. For applications that need to read, inspect, or manipulate existing PDFs, gopdf is not the right tool.

Maintenance and Installation

The last push to the repository was on 2026-09-12. The repository is not archived. There are no GitHub releases and no tagged versions; the module path is `github.com/signintech/gopdf` and the go.mod sets `go 1.13`.

Installation uses the standard Go module command:

go get -u github.com/signintech/gopdf

The license is MIT. The repository includes a SECURITY.md and a Changelog.md at the root, and the examples directory contains subdirectories for Arabic text, clip-polygon, mask-image, mask-with-rotated-image, outline, and table use cases.

Editorial conclusion

gopdf suits Go backend services that need to generate documents without a rendering engine dependency. Its TTF subfont embedding makes it viable for applications that produce Chinese, Japanese, or Korean text. The API is lower-level than layout-focused alternatives: placing text and shapes requires explicit coordinates, so building complex paginated documents takes more code. Engineers who need a report layout system rather than precise coordinate control should evaluate a wrapper library built on top of gopdf or a different generator. The library has no GitHub releases and no tagged versions; pin to a specific commit hash rather than using the latest module path if reproducible builds matter.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. signintech/gopdf on GitHub