Go

Last updated: 2026-06-29

The rustpdf-go module wraps the rust-pdf C core with idiomatic Go types over cgo. It covers the whole product surface: vector graphics, embedded/subset fonts & Unicode text, paragraphs, images, PDF/A (1b–3a + A-4/4e/4f), tagged/accessible output, attachments, AcroForm fields, manipulation, text extraction, encryption and digital signatures. The native library is statically linked from a prebuilt archive bundled per platform, so go get + go build works, with no separate native install.

Installation

Add the module with go get. A prebuilt static libpdf_ffi.a for your platform ships inside the module (under lib/<os>_<arch>/), so there is nothing else to install or compile.

go get github.com/rustpdf/rustpdf-go@latest

Requires Go 1.21+ and a C compiler on PATH (cgo, enabled by default). Supported platforms: darwin/arm64, darwin/amd64, linux/amd64, linux/arm64, windows/amd64. Import it (the package is named rustpdf):

import rustpdf "github.com/rustpdf/rustpdf-go"

fmt.Println(rustpdf.Version())   // native library version

Quick start

A one-page document with a filled rectangle, saved to disk. Errors are elided with _ for brevity. See Error handling for the real pattern:

package main

import rustpdf "github.com/rustpdf/rustpdf-go"

func main() {
	doc, _ := rustpdf.New()       // A4 by default
	defer doc.Close()

	_ = doc.AddPage()
	_ = doc.SetFillRGB(0.86, 0.20, 0.18)
	_ = doc.Rect(72, 640, 200, 120)   // x, y, width, height (points)
	_ = doc.Fill()
	_ = doc.Save("out.pdf")
}

Get the bytes instead of writing a file with ToBytes:

doc, _ := rustpdf.New()
defer doc.Close()
font, _ := doc.AddFontFile("Roboto-Regular.ttf")
_ = doc.AddPage()
_ = doc.SetFillRGB(0.1, 0.1, 0.12)
_ = doc.Rect(0, 800, 595, 42)
_ = doc.Fill()
_ = doc.ShowText(font, 24, 72, 740, "Olá, açúcar — café", 0)
data, _ := doc.ToBytes()           // []byte instead of a file

cgo & deployment

The binding links the native library statically, so a built binary carries it. There is no shared library to ship alongside.

• Build host needs a C toolchain. cgo is on by default (CGO_ENABLED=1); install a C compiler (Xcode CLT on macOS, build-essential on Linux, MinGW-w64 on Windows).
• Cross-compilation needs a cross C toolchain for the target (set CC), because cgo invokes the platform C compiler. Pure GOOS/GOARCH cross-builds without a cross-CC won't link.
• The bundled archive is per-platform. Building for a target outside the supported set above has no archive to link against.
• Containers: build inside an image that has the C toolchain; the resulting binary needs only the usual system libs at runtime (no rust-pdf shared object).

Licensing & activation

Basic generation (everything above) is always free. The corporate features (PDF/A, digital signatures/PAdES, encryption, accessibility) require an active license token. Without one, those calls return an *Error and produce no output.

Activation needs no rebuild. Easiest is an environment variable, auto-activated the first time a corporate feature is used:

export RUSTPDF_LICENSE="010f0000…"           # the token we email you
# or point at a file:
export RUSTPDF_LICENSE_FILE=/etc/rustpdf/license.txt

Or activate explicitly in code:

if err := rustpdf.ActivateLicense(token); err != nil {
	log.Fatal(err)   // forged / expired / malformed
}

Coordinate system

• Units are points (1 pt = 1/72 inch). A4 is 595 × 842, US Letter 612 × 792.
• The origin (0, 0) is the bottom-left corner; y grows upward.
• For text, (x, y) is the baseline of the first glyph.
• Drawing/text always targets the most recently added page.

Goroutines & concurrency

Every native call is synchronous and the core is Send but not Sync: a single handle must never be touched by two goroutines at once.

• Documents are independent. Each Document/EditableDoc shares no state, so building several in parallel goroutines is fine, with one handle per goroutine.
• Don't share a live handle across goroutines; give each its own (or guard it with a mutex).
• Errors are per-thread. The native last-error is thread-local, so a failure in one goroutine never clobbers another's, and the message surfaces on the calling side.
• License is process-global. ActivateLicense (or the env var) applies everywhere; activate once at startup.

var wg sync.WaitGroup
for i := 0; i < 4; i++ {
	wg.Add(1)
	go func(n int) {
		defer wg.Done()
		doc, _ := rustpdf.New()      // one document per goroutine
		defer doc.Close()
		_ = doc.AddPage()
		_ = doc.SetFillRGB(0.1, 0.1, 0.12)
		_ = doc.Rect(72, 700, 200, 80)
		_ = doc.Fill()
		_ = doc.Save(fmt.Sprintf("out-%d.pdf", n))
	}(i)
}
wg.Wait()

Authoring: create & save

Creates an empty document (A4 default page size). Call Close() to free the native handle.

Pages & vector graphics

Graphics state and path operators mirror PDF's content-stream model. Colors are RGB in 0.0–1.0.

doc, _ := rustpdf.New()
defer doc.Close()
_ = doc.AddPage()
_ = doc.SetStrokeRGB(0.10, 0.45, 0.90)
_ = doc.SetLineWidth(3)
_ = doc.Rect(72, 600, 300, 160)
_ = doc.Stroke()
_ = doc.SetFillRGB(0.95, 0.77, 0.06)
_ = doc.Rect(120, 640, 120, 80)
_ = doc.Fill()
_ = doc.Save("shapes.pdf")

Fonts & text

Fonts are embedded and subsetted, with HarfBuzz-quality shaping, kerning and full Unicode (Type0/CIDFontType2 with ToUnicode, so text extracts and copies correctly, provided the embedded font covers those characters). Register a font once, then reference it by its integer id.

headingLevel (1–6) tags the run as H1–H6 in an accessible document (see Accessibility); pass 0 for ordinary text.

doc, _ := rustpdf.New()
defer doc.Close()
regular, _ := doc.AddFontFile("Roboto-Regular.ttf")
// …or from bytes you already have in memory:
// data, _ := os.ReadFile("Roboto-Regular.ttf"); regular, _ := doc.AddFont(data)

_ = doc.AddPage()
_ = doc.ShowText(regular, 28, 72, 760, "Invoice #1024", 0)
_ = doc.ShowText(regular, 12, 72, 720, "日本語 · Ελληνικά · العربية", 0)
_ = doc.Save("text.pdf")

Paragraphs

The paragraph layer wraps, aligns and justifies text inside a fixed width (greedy line breaking using shaped glyph widths).

intro := "A long paragraph that wraps to the given width and is justified " +
	"automatically; extra space is distributed between words."

doc, _ := rustpdf.New()
defer doc.Close()
f, _ := doc.AddFontFile("Roboto-Regular.ttf")
_ = doc.AddPage()
_ = doc.Paragraph(f, 12, 72, 700, 451, intro, rustpdf.AlignJustify)
_ = doc.Save("paragraph.pdf")

See the Align enum for the alignment options.

Images

JPEGs are embedded verbatim (DCTDecode, no re-encode). PNGs are decoded and re-encoded (FlateDecode); alpha becomes an /SMask, palette becomes an Indexed color space. Register an image once, draw it many times.

doc, _ := rustpdf.New()
defer doc.Close()
logo, _ := doc.AddImageFile("logo.png")
_ = doc.AddPage()
_ = doc.DrawImage(logo, 72, 680, 160, 90)
_ = doc.Save("with_image.pdf")

PDF/A licensed

Produce archival-grade output. Pdfa() defaults to A-2b; PdfaLevel(level) selects a specific PdfaLevel. An embedded sRGB ICC profile, output intent, XMP metadata and document /ID are added automatically; A-1b also forces PDF 1.4 and emits a /CIDSet, and A-4 (ISO 19005-4) is based on PDF 2.0.

doc, _ := rustpdf.New()
defer doc.Close()
_ = doc.PdfaLevel(rustpdf.A2b)
_ = doc.SetInfo(rustpdf.Info{Title: "Q3 Report", Author: "Acme Inc."})
f, _ := doc.AddFontFile("Roboto-Regular.ttf")
_ = doc.AddPage()
_ = doc.ShowText(f, 20, 72, 760, "Archival report", 0)
if err := doc.Save("report_pdfa.pdf"); err != nil {
	log.Fatal(err)   // *Error without a license granting PDF/A
}

Accessibility (Tagged PDF / PDF/UA) licensed

Tagged() builds a logical structure tree (PDF/UA-1). Combine with PdfaLevel(rustpdf.A2a) for archival and accessible output. Use headingLevel on ShowText for H1–H6, and Figure(..., alt) for described images.

doc, _ := rustpdf.New()
defer doc.Close()
_ = doc.PdfaLevel(rustpdf.A2a)
_ = doc.Tagged()
_ = doc.SetInfo(rustpdf.Info{Title: "Accessible report"})
f, _ := doc.AddFontFile("Roboto-Regular.ttf")
_ = doc.AddPage()
_ = doc.ShowText(f, 26, 72, 760, "Annual report", 1)   // H1
_ = doc.ShowText(f, 14, 72, 720, "Overview", 2)         // H2
_ = doc.ShowText(f, 11, 72, 690, "Body paragraph of the section…", 0)
chart, _ := doc.AddImageFile("chart.png")
_ = doc.Figure(chart, 72, 520, 300, 150, "Revenue grew 18% year over year")
_ = doc.Save("accessible.pdf")

Attachments (PDF/A-3) licensed

PDF/A-3 allows embedding arbitrary source files (e.g. the XML behind an e-invoice). Each attachment carries a MIME type and an AFRelationship.

xml, _ := os.ReadFile("invoice.xml")

doc, _ := rustpdf.New()
defer doc.Close()
_ = doc.PdfaLevel(rustpdf.A3b)
_ = doc.SetInfo(rustpdf.Info{Title: "E-invoice 1024"})
f, _ := doc.AddFontFile("Roboto-Regular.ttf")
_ = doc.AddPage()
_ = doc.ShowText(f, 18, 72, 760, "Invoice 1024", 0)
_ = doc.AttachFile("invoice.xml", "text/xml", xml,
	rustpdf.RelSource, "Structured invoice data")
_ = doc.Save("einvoice.pdf")

ZUGFeRD / Factur-X e-invoices licensed

Turn the document into a ZUGFeRD / Factur-X electronic invoice: the embedded XML (the Cross-Industry Invoice) is attached as factur-x.xml, the file is marked PDF/A-3, and the Factur-X identification is written into the XMP metadata. The visible PDF is the human-readable invoice; the embedded XML is its machine-readable twin. Validates as PDF/A-3 + Factur-X under veraPDF.

xml, _ := os.ReadFile("factur-x.xml")        // your Cross-Industry Invoice XML

doc, _ := rustpdf.New()
defer doc.Close()
_ = doc.SetInfo(rustpdf.Info{Title: "Invoice INV-2026-001"})
f, _ := doc.AddFontFile("Roboto-Regular.ttf")
_ = doc.AddPage()
_ = doc.ShowText(f, 18, 72, 760, "Invoice INV-2026-001", 0)
_ = doc.Facturx(xml, rustpdf.FacturxEN16931)
_ = doc.Save("einvoice.pdf")        // PDF/A-3 + Factur-X; needs a PDF/A license

See the FacturxProfile enum for the conformance levels (FacturxMinimum through FacturxExtended).

AcroForm fields

Build interactive forms with generated appearance streams (no NeedAppearances). Rectangles are [4]float64{x0, y0, x1, y1}; page is a 0-based page index. Dotted names ("a.b.c") create hierarchical fields.

doc, _ := rustpdf.New()
defer doc.Close()
_ = doc.AddPage()
_ = doc.TextField("applicant.name", 0, [4]float64{72, 700, 320, 720}, "", 0)
_ = doc.Checkbox("agree", 0, [4]float64{72, 660, 88, 676}, false)
_ = doc.Dropdown("plan", 0, [4]float64{72, 620, 240, 640},
	[]string{"Starter", "Pro", "Enterprise"}, 1, 0)
_ = doc.RadioGroup("billing", 0, []rustpdf.RadioButton{
	{Rect: [4]float64{72, 580, 88, 596}, Export: "monthly"},
	{Rect: [4]float64{140, 580, 156, 596}, Export: "annual"},
}, 1)
_ = doc.Save("form.pdf")

Fill and flatten fields later with EditableDoc.

Hyperlinks free

Add clickable link rectangles to the current page: a web link opens a URL; an internal link jumps to another page (optionally scrolling so a given top y-coordinate sits at the top of the view).

doc, _ := rustpdf.New()
defer doc.Close()
f, _ := doc.AddFontFile("Roboto-Regular.ttf")
_ = doc.AddPage()
_ = doc.ShowText(f, 14, 72, 760, "Visit rustpdf.dev (see page 2)", 0)
_ = doc.LinkURI([4]float64{72, 756, 320, 776}, "https://rustpdf.dev/")   // web link
top := 800.0
_ = doc.LinkToPage([4]float64{330, 756, 430, 776}, 1, &top)              // jump to page 2
_ = doc.AddPage()
_ = doc.Save("links.pdf")

Rectangles are [4]float64{x0, y0, x1, y1} in points; pageIndex is 0-based. Pass nil for top to keep the current scroll position.

Bookmarks / outline free

Build a navigable document outline. A Bookmark has a title, a target page and an optional Top; nest children with .Child(...) (or by setting the Children slice). A document with bookmarks opens with the outline pane shown.

doc, _ := rustpdf.New()
defer doc.Close()
_, _ = doc.AddFontFile("Roboto-Regular.ttf")
for i := 0; i < 3; i++ {
	_ = doc.AddPage()
}
top := 820.0
_ = doc.AddBookmark(
	rustpdf.Bookmark{Title: "Chapter 1", Page: 0, Top: &top}.
		Child(rustpdf.Bookmark{Title: "Section 1.1", Page: 1}).
		Child(rustpdf.Bookmark{Title: "Section 1.2", Page: 2}))
_ = doc.AddBookmark(rustpdf.Bookmark{Title: "Chapter 2", Page: 2})
_ = doc.Save("outline.pdf")

Metadata

Sets the document information dictionary (and, for PDF/A, the matching XMP). Set only the fields you need.

_ = doc.SetInfo(rustpdf.Info{
	Title:    "Q3 Report",
	Author:   "Acme Inc.",
	Subject:  "Quarterly results",
	Keywords: "finance, q3",
})

Manipulation: load an existing PDF

EditableDoc parses an existing document (classic & xref streams, object streams, all standard filters, RC4/AES decryption) into an editable model. Pages are a flat list; the page tree is rebuilt on output.

data, _ := os.ReadFile("in.pdf")
ed, _ := rustpdf.Load(data)
defer ed.Close()
fmt.Println(ed.PageCount())

To open a password-protected document, pass the user or owner password. The wrong password returns an *Error rather than loading garbage.

data, _ := os.ReadFile("secured.pdf")
ed, err := rustpdf.LoadWithPassword(data, "owner-secret")
if err != nil {
	log.Fatal(err)   // *Error on a wrong password
}
defer ed.Close()
fmt.Println(ed.PageCount())

Pages: merge, split, reorder, rotate

ad, _ := os.ReadFile("a.pdf")
bd, _ := os.ReadFile("b.pdf")
a, _ := rustpdf.Load(ad)
defer a.Close()
b, _ := rustpdf.Load(bd)
_ = a.Merge(b)                 // a now has a's pages followed by b's
b.Close()
_ = a.RotatePage(0, 90)
_ = a.Save("merged.pdf")

sub, _ := a.ExtractPages([]int{0, 2})   // pages 1 and 3
defer sub.Close()
_ = sub.Save("subset.pdf")

Metadata, overlay & form fill

data, _ := os.ReadFile("form.pdf")
ed, _ := rustpdf.Load(data)
defer ed.Close()
_ = ed.SetInfo("Title", "Filled form")
found, _ := ed.FillTextField("applicant.name", "Jane Doe")
title, _ := ed.GetInfo("Title")
fmt.Println("filled:", found, "| title:", title)
_ = ed.Save("filled.pdf")

Form fill & flatten free

Fill the fields of an existing AcroForm and (optionally) flatten them: filling generates a fresh appearance stream (no NeedAppearances), and flattening bakes every widget's appearance into the page content and removes the interactive form entirely. The setter methods return (bool, error): the bool reports whether a field with that name was found.

data, _ := os.ReadFile("form.pdf")
ed, _ := rustpdf.Load(data)
defer ed.Close()
names, _ := ed.FieldNames()                 // ["applicant.name", "agree", "plan", ...]
fmt.Println(names)
_, _ = ed.FillTextField("applicant.name", "Jane Doe")
_, _ = ed.SetCheckbox("agree", true)
_, _ = ed.SetRadio("billing", "annual")
_, _ = ed.SetChoice("plan", "Pro")
_ = ed.FlattenForms()                       // optional: make it non-editable
_ = ed.Save("filled.pdf")

Watermarks free

Stamp a diagonal text watermark or a centered image watermark across every page, drawn semi-transparently over the existing content. Text uses the standard Helvetica font, so keep it to WinAnsi (Latin-1) for stamps like "CONFIDENTIAL". The color is RGB in 0.0..1.0, opacity in 0.0..1.0, and rotation is in degrees. opaqueBackground draws a solid white box behind the text first (a white-out stamp). WatermarkImageFile now also takes a rotationDeg.

data, _ := os.ReadFile("report.pdf")
ed, _ := rustpdf.Load(data)
defer ed.Close()
_ = ed.WatermarkText("CONFIDENTIAL", 64, 0.5, 0.5, 0.5, 0.25, 45, false)
_ = ed.WatermarkImageFile("stamp.png", 64, 64, 0.3, 30)
_ = ed.Save("stamped.pdf")

Positioned drawing free

Place a filled rectangle or a line of text at exact coordinates on one page, handy for masking a value and stamping a new one over it. Coordinates are in the page's visible space (origin lower-left, y up), so content lands where a viewer sees it regardless of the page's /Rotate. FillRect takes RGB (each 0.0..1.0) and opacity (0.0..1.0); pass opacity 1 for an opaque white-out box. PlaceText draws in standard Helvetica (so keep text to WinAnsi / Latin-1), and rotationDeg rotates the text counter-clockwise about its anchor (x, y). DrawImage takes raw JPEG/PNG image bytes and places the image with its lower-left corner at (x, y) scaled to width × height points. All three return whether the target page existed.

PlaceTextAligned is PlaceText with a horizontal Align (AlignLeft/AlignRight/AlignCenter): the start point is shifted along the baseline by the text width so the line is anchored left, right or centered on (x, y). MaskedText is the one-call mask-and-replace: it fills an opaque box [x, y, x+width, y+height] in bgColor, then writes text in textColor horizontally aligned per align and vertically centered in the box. Colors are [3]float64 RGB triples (each 0.0..1.0). Both also draw in standard Helvetica.

data, _ := os.ReadFile("invoice.pdf")
ed, _ := rustpdf.Load(data)
defer ed.Close()
g, _ := rustpdf.MeasurePage(data, 0)
fmt.Printf("page is %.0fx%.0f pt\n", g.Width, g.Height)
// mask the old total with an opaque white box, then stamp the new value
ed.FillRect(0, 430, 690, 110, 18, 1, 1, 1, 1)
ed.PlaceText(0, 435, 693, "PAID IN FULL", 12, 0, 0.5, 0, 0)
// center a label on a point
ed.PlaceTextAligned(0, 300, 660, "RECEIPT", 14, 0, 0, 0, 0, rustpdf.AlignCenter)
// mask a placeholder and write right-aligned white text over a blue box in one call
ed.MaskedText(0, 430, 640, 110, 18, "R$ 1.240,00", 12,
	[3]float64{1, 1, 1}, [3]float64{0, 0, 0.6}, rustpdf.AlignRight)
logo, _ := os.ReadFile("logo.png")
ed.DrawImage(0, logo, 435, 720, 120, 48, 0) // stamp a logo, lower-left at (435, 720)
_ = ed.Save("stamped.pdf")

Advanced stamping: fonts, anchors & paragraphs free

The anchored variants extend the positioned-drawing primitives with embedded fonts, explicit vertical anchoring, padded masked text, wrapped paragraphs, an alternate coordinate space and an image rotation anchor. See the interactive positioning guide for a visual tour of the anchor and space semantics.

Embedded stamping fonts

AddFontFile/AddFont register a TrueType/OpenType font on a loaded document and return a fontID for the stamping calls below. The font is embedded as a subset, so stamped text renders with the real glyphs and metrics (full Unicode, no WinAnsi limit). Pass fontID = -1 anywhere to keep the built-in Helvetica.

Vertical anchors

PlaceTextAnchored is PlaceTextAligned plus a VerticalAnchor saying what y means: AnchorBaseline (the historical behavior), AnchorTop (the text hangs from y: baseline at y − ascent × size, legacy fixed-position layout semantics), AnchorBottom (the descender line rests on y), and AnchorLineTop/AnchorLineBottom, which anchor the layout line box (OS/2 win metrics plus a fixed half-leading); use the line-box anchors to match legacy layout engines line placement exactly. Ascent/descent come from the selected font's metrics.

Masked text: vertical alignment & padding

MaskedTextPadded is MaskedText plus a VerticalAlign for the line inside the box (VAlignMiddle keeps the historical cap-height centering; VAlignTop hangs the line from the top edge, top line-alignment in rectangle-based text APIs semantics; VAlignBottom rests the descender line on the bottom edge), a horizontal edge inset padding in points for left/right alignment (text starts at x + padding or ends at x + width − padding; a negative value keeps the historical default min(0.15 × size, width / 4), 0 starts flush with the box edge) and an optional embedded fontID.

Paragraphs with word wrapping

PlaceParagraph breaks text into lines that fit width points (greedy, by word; \n forces a break) and draws them downward from the anchor (x, y). anchor positions the block: AnchorTop is the top of the box (first baseline ascent × size below y); AnchorBaseline is the first line's baseline; AnchorBottom/AnchorLineBottom are bottom-pinned: the block's bottom rests on y and grows upward by its real content height. maxHeight > 0 is a ceiling that truncates overflowing lines (with a bottom anchor they are cut from the top and the last lines stay pinned); <= 0 means unlimited. lineHeight scales the default 1.2 × size leading (<= 0 = 1.0); rotationDeg rotates the laid-out block about the anchor. It returns the number of lines drawn and the measured block height in points, so you can stack blocks without re-measuring.

Coordinate space

SetStampSpace chooses the coordinate space of all positioned stamping calls that follow it. StampVisible (the default) keeps the historical behavior: coordinates in the page's displayed space, compensating /Rotate so a rotationDeg = 0 stamp reads upright on screen. StampMedia interprets coordinates and rotations in the raw PDF user space (the raw-coordinate semantics of legacy layout engines), never composing with the page's /Rotate or crop offset; use it to reproduce coordinates computed for legacy PDF libraries on rotated (scanned) pages. Watermarks and redaction are unaffected.

Image rotation anchor

DrawImageAnchored is DrawImage plus an ImageAnchor: ImageAnchorCorner (the DrawImage behavior) rotates the image about its own lower-left corner at (x, y), so it sweeps around the anchor; ImageAnchorBoundingBox lands the rotated image's bounding box with its lower-left at (x, y) (bounding-box layout semantics: a 90° image occupies [x, x+height] × [y, y+width] and the pixels always sit at/above/right of the anchor).

data, _ := os.ReadFile("form.pdf")
ed, _ := rustpdf.Load(data)
defer ed.Close()

// stamp with a real font (embedded as a subset)
roboto, _ := ed.AddFontFile("Roboto-Regular.ttf")

// hang a label from y = 700 using the layout line box
ed.PlaceTextAnchored(0, 72, 700, "Cláusula 4 — Confidencialidade", 12,
	0, 0, 0, 0, rustpdf.AlignLeft, rustpdf.AnchorLineTop, roboto)

// mask a placeholder: line hangs from the box top, flush with the left edge
ed.MaskedTextPadded(0, 430, 640, 110, 18, "R$ 1.240,00", 12,
	[3]float64{0, 0, 0}, [3]float64{1, 1, 1},
	rustpdf.AlignLeft, rustpdf.VAlignTop, 0, roboto)

// wrapped paragraph pinned to a bottom edge, capped at 80 pt
lines, height, _ := ed.PlaceParagraph(0, 72, 120, 300,
	"Long disclaimer text that wraps across several lines…", 9,
	0.3, 0.3, 0.3, rustpdf.AlignJustify, roboto,
	80, 1.0, rustpdf.AnchorBottom, 0)
fmt.Printf("drew %d lines, %0.1f pt tall\n", lines, height)

// reproduce legacy raw-space coordinates on a rotated scan
ed.SetStampSpace(rustpdf.StampMedia)
ed.PlaceTextAnchored(0, 100, 250, "legacy-style position", 10,
	0, 0, 0, 90, rustpdf.AlignLeft, rustpdf.AnchorBaseline, -1)
ed.SetStampSpace(rustpdf.StampVisible)

// rotated logo whose bounding box lands at (400, 300)
logo, _ := os.ReadFile("logo.png")
ed.DrawImageAnchored(0, logo, 400, 300, 120, 48, 90, rustpdf.ImageAnchorBoundingBox)
_ = ed.Save("stamped.pdf")

Redaction licensed

True redaction: the text and graphics whose origin falls inside a rectangle are removed from the content stream (not just covered), so the data is gone from the file and is no longer extractable. Opaque black boxes are then painted over the regions. Returns whether the target page existed.

data, _ := os.ReadFile("statement.pdf")
ed, _ := rustpdf.Load(data)
defer ed.Close()
// rects = list of [4]float64{x0, y0, x1, y1} on that page
ok, err := ed.Redact(0, [][4]float64{
	{60, 590, 400, 620},
	{60, 540, 400, 570},
})
if err != nil {
	log.Fatal(err)   // *Error without a license granting redaction
}
fmt.Println("page found:", ok)
_ = ed.Save("redacted.pdf")

Convert to PDF/A licensed

Convert an existing PDF to archival PDF/A (a basic profile: A-1b, A-2b or A-3b). An sRGB output intent, PDF/A XMP metadata (synced with /Info) and a document /ID are added. Fails if any font is not embedded (PDF/A requires every font embedded) or if a level-A profile is requested.

data, _ := os.ReadFile("in.pdf")
ed, _ := rustpdf.Load(data)
defer ed.Close()
if err := ed.ConvertToPdfa(rustpdf.A2b); err != nil {
	log.Fatal(err)   // *Error if fonts aren't embedded
}
_ = ed.Save("archival.pdf")     // veraPDF: PDF/A-2b compliant

Optimize & compact

data, _ := os.ReadFile("big.pdf")
ed, _ := rustpdf.Load(data)
defer ed.Close()
_ = ed.Optimize()
_ = ed.Compact(true)
_ = ed.Save("small.pdf")

Encryption licensed

Apply standard-handler encryption at output. AES-256 (V5/R6) uses OS-CSPRNG keys/IVs.

data, _ := os.ReadFile("in.pdf")
ed, _ := rustpdf.Load(data)
defer ed.Close()
if err := ed.Encrypt(rustpdf.AES256, "", "owner-secret", true); err != nil {
	log.Fatal(err)   // *Error without an Encryption license
}
_ = ed.Save("secured.pdf")

See the Encryption enum for RC4 / AES-128 / AES-256.

Output & incremental update

original, _ := os.ReadFile("in.pdf")
ed, _ := rustpdf.Load(original)
defer ed.Close()
_ = ed.SetInfo("Subject", "reviewed")
incremental, _ := ed.ToBytesIncremental(original)   // original bytes preserved verbatim
_ = os.WriteFile("reviewed.pdf", incremental, 0o644)

Normalize & downgrade free

Adjust the output PDF version and strip PDF/A conformance. SetVersion sets the version code (0 = 1.4, 1 = 1.5, 2 = 1.7, 3 = 2.0). StripPdfa removes the catalog /OutputIntents and the XMP pdfaid identifier so the file is no longer claimed as PDF/A. Normalize does both in one call.

data, _ := os.ReadFile("archival.pdf")
ed, _ := rustpdf.Load(data)
defer ed.Close()
_ = ed.Normalize(2)   // strip PDF/A + downgrade to PDF 1.7
_ = ed.Save("plain.pdf")

Digital signatures licensed

Sign a PDF with a PKCS#7 detached signature via an incremental update (the original bytes are preserved). Keys and certificates are passed as DER bytes. PAdES: true switches to PAdES-B-B.

pdf, _ := os.ReadFile("contract.pdf")
keyDER, _ := os.ReadFile("signing-key.pkcs8.der")   // PKCS#8 private key (DER)
certDER, _ := os.ReadFile("signing-cert.der")       // X.509 certificate (DER)

signed, err := rustpdf.Sign(pdf, keyDER, certDER, rustpdf.SignOptions{
	Reason: "Approved", Location: "New York",
	Name: "Jane Doe", PAdES: true,
})
if err != nil {
	log.Fatal(err)
}
_ = os.WriteFile("contract.signed.pdf", signed, 0o644)
// Verify in a shell: pdfsig contract.signed.pdf  →  "Signature is Valid."

Deferred / HSM signing licensed

Sign without ever handing the library a private key. The key stays in an HSM, cloud KMS, smartcard or PKI token; you supply only the signer certificate and a way to produce the raw RSA PKCS#1 v1.5 signature over SHA-256. This works with any PKI (eIDAS, AATL and other trust frameworks). Two models are available: a one-call form with a sign-hash callback, and a two-phase form for asynchronous signers where you build the CMS container yourself.

Model A. SignWith assembles the CMS signed attributes, calls signHash for the raw signature, then embeds the finished CMS. certDER is the signer certificate; chain are intermediate certificates (DER), supplied independently of the key; options may be nil.

pdf, _ := os.ReadFile("contract.pdf")
certDER, _ := os.ReadFile("signer.der")       // X.509 certificate (DER), no key

signed, err := rustpdf.SignWith(pdf, certDER,
	func(tbs []byte) ([]byte, error) {
		return hsm.SignRSA(tbs)               // remote HSM / KMS / smartcard
	},
	nil,                                      // chain: intermediate certs (DER)
	&rustpdf.SigningOptions{Reason: "Approved", PAdES: true})
if err != nil {
	log.Fatal(err)
}
_ = os.WriteFile("contract.signed.pdf", signed, 0o644)

Model B. For an asynchronous signer, drive the two-phase flow. BeginSigning returns a SigningSession exposing the placeholder document, the exact covered bytes and their SHA-256 hash. Hand the hash to the remote signer, build the DER CMS / PKCS#7 container yourself, then complete the signature. The session methods are Document() []byte, Bytes() []byte, Hash() [32]byte and Complete(container []byte) ([]byte, error).

sess, _ := rustpdf.BeginSigning(pdf, &rustpdf.SigningOptions{PAdES: true})
digest := sess.Hash()                         // [32]byte, SHA-256 of sess.Bytes()

container := buildCMS(digest, certDER, sig)   // your DER CMS / PKCS#7
final, err := sess.Complete(container)        // or rustpdf.CompleteSignature(sess.Document(), container)
if err != nil {
	log.Fatal(err)
}
_ = os.WriteFile("contract.signed.pdf", final, 0o644)

List the signature fields already present before signing, to detect an existing signature or pick a target field. An empty slice means there are no signature fields.

fields, _ := rustpdf.ListSignatures(pdf)
for _, f := range fields {
	fmt.Printf("%s signed:%v\n", f.Name, f.Signed) // SignatureField{Name, Signed}
}

SigningOptions carries Reason, Location, Name, PAdES (produce a PAdES-B-B signature), Certify (a DocMDP certification level, use only on the first signature), ContainerSize (reserved /Contents bytes; 0 uses the default, raise it for large cloud CMS containers) and Policy (an optional PAdES-EPES signature-policy identifier).

For a visible signature, set Visible: true with VisiblePage (0-based), VisibleRect ([4]float64{x0, y0, x1, y1} in points) and optional VisibleText (lines separated by \n). VisibleImage accepts a PNG or JPEG (e.g. a scanned handwritten signature) drawn aspect-fit behind any text.

img, _ := os.ReadFile("signature.png")
opts := &rustpdf.SigningOptions{
	Visible:      true,
	VisiblePage:  0,
	VisibleRect:  [4]float64{72, 72, 272, 144},
	VisibleText:  "Jane Doe\nApproved",
	VisibleImage: img,   // PNG/JPEG drawn aspect-fit behind the text
}

Certify

SignaturePolicy (for Policy) carries the policy OID (dotted-decimal), the policy document Hash, an optional HashAlgorithmOID (SHA-256 when empty) and an optional URI where the policy can be retrieved.

Timestamp & DSS (PAdES LTV) licensed

Build long-term-validation signatures offline. AddDss appends a Document Security Store (/DSS with certs/CRLs, PAdES-B-LT); Timestamp appends an RFC 3161 document timestamp (/DocTimeStamp, PAdES-B-LTA).

signed, _ := os.ReadFile("contract.signed.pdf")

// B-LT: embed validation material (caller supplies DER certs/CRLs)
lt, _ := rustpdf.AddDss(signed, [][]byte{certDER}, [][]byte{crlDER})

// B-LTA: add a document timestamp signed by a TSA key/cert (date "" = now)
lta, _ := rustpdf.Timestamp(lt, tsaKeyDER, tsaCertDER, "")
_ = os.WriteFile("contract.lta.pdf", lta, 0o644)

Network timestamp (AD-RT)

For a trusted document timestamp from a real Time Stamping Authority, use the transport-agnostic helpers and do the HTTP POST yourself. BeginTimestamp prepares the document and returns the bytes to timestamp; build an RFC 3161 request with TimestampRequest, POST it to the TSA, extract the token with TimestampTokenFromResponse, then embed it with CompleteSignature. Free public TSAs work (FreeTSA https://freetsa.org/tsr, DigiCert http://timestamp.digicert.com).

document, tbs, _ := rustpdf.BeginTimestamp(signed)
imprint := sha256.Sum256(tbs)
req, _ := rustpdf.TimestampRequest(imprint[:], nil, true)

// you POST the request to the TSA (application/timestamp-query)
resp, _ := http.Post("https://freetsa.org/tsr", "application/timestamp-query",
	bytes.NewReader(req))
body, _ := io.ReadAll(resp.Body)

token, _ := rustpdf.TimestampTokenFromResponse(body)
final, _ := rustpdf.CompleteSignature(document, token)
_ = os.WriteFile("contract.tsa.pdf", final, 0o644)

Validate signatures licensed

Validate every signature in a PDF: each report recomputes the /ByteRange digest, parses the CMS, and checks that the cryptographic signature is valid, that the messageDigest matches the covered bytes, and whether the signature covers the whole document.

Each SignatureReport has FieldName and Signer (both *string, and nil when absent, so dereference only after a nil check as the example does for Signer), plus SubFilter, CoversWholeDocument, DigestValid, SignatureValid, IsValid and ByteRange. Each report also carries certificate and signature details: Issuer, SerialNumber, ValidFrom, ValidTo, Algorithm (e.g. SHA256withRSA) and SigningTime (all *string, any may be nil), plus CertCount (certificates embedded in the CMS) and HasTimestamp (whether a signature timestamp is present). An empty slice means the document is unsigned. Signature validation is a licensed feature: this call requires an active license (signatures) even when the document is unsigned, and is not available on the free tier.

data, _ := os.ReadFile("contract.signed.pdf")
reports, _ := rustpdf.VerifySignatures(data)
for _, sig := range reports {
	signer := "(unknown)"
	if sig.Signer != nil {
		signer = *sig.Signer
	}
	fmt.Printf("%s valid:%v covers whole doc:%v\n",
		signer, sig.IsValid, sig.CoversWholeDocument)
	if sig.Issuer != nil {
		fmt.Printf("  issuer:%s certs:%d timestamp:%v\n",
			*sig.Issuer, sig.CertCount, sig.HasTimestamp)
	}
	if sig.Algorithm != nil {
		fmt.Printf("  algorithm:%s\n", *sig.Algorithm)
	}
}

Text & image extraction

Extract a document's text, mapping shown glyph codes back to Unicode through each font's ToUnicode map, with space/line inference. Raster images can be pulled out too: JPEGs are written verbatim as .jpg, everything else as .png. The output directory is created automatically if it does not already exist.

data, _ := os.ReadFile("report.pdf")
text, _ := rustpdf.ExtractText(data)
fmt.Println(text)

n, _ := rustpdf.ExtractImagesToDir(data, "out_images/")   // returns how many were written
fmt.Printf("wrote %d image(s)\n", n)

Page geometry free

Read the size and rotation of every page without mutating the file. Sizes are in PDF points (72 per inch). Width and Height ignore the page's /Rotate, while RotatedWidth and RotatedHeight account for it (swapped for 90/270-degree pages). Each PageGeometry also carries the MediaBox and CropBox as a PdfRect{X0, Y0, X1, Y1} (with Width() and Height() helpers). MeasurePage returns an *Error when the index is out of range.

data, _ := os.ReadFile("report.pdf")
pages, _ := rustpdf.MeasurePages(data)
for _, p := range pages {
	fmt.Printf("page %d: %.0fx%.0f pt, rotation %d (visible %.0fx%.0f)\n",
		p.Page, p.Width, p.Height, p.Rotation, p.RotatedWidth, p.RotatedHeight)
}

g, err := rustpdf.MeasurePage(data, 0)
if err != nil {
	log.Fatal(err)   // *Error when the index is out of range
}
fmt.Printf("crop box %.0fx%.0f\n", g.CropBox.Width(), g.CropBox.Height())

Document inspection free

Get a non-mutating overview of a PDF, its version, PDF/A level, encryption posture and page count, without opening or decrypting it. PdfaLevel is empty when the document is not PDF/A. Encryption is one of "None", "RC4", "AES-128" or "AES-256", and RequiresPassword reports whether a user password is needed to open it. Inspect never fails on a password-locked file.

data, _ := os.ReadFile("report.pdf")
ov, _ := rustpdf.Inspect(data)
fmt.Printf("PDF %s, %d page(s)\n", ov.Version, ov.PageCount)
fmt.Printf("PDF/A level: %q\n", ov.PdfaLevel)        // "" when not PDF/A
fmt.Printf("encrypted: %v (%s)\n", ov.Encrypted, ov.Encryption)
fmt.Printf("needs password: %v\n", ov.RequiresPassword)

Positional text search free

Find every occurrence of a query string and get its bounding box, useful for highlighting or redaction targeting. With caseSensitive false the match is case-insensitive. Each TextHit carries Page, Text and the box X, Y, Width, Height in PDF points (origin lower-left). An empty slice means no match. See the concept page Search inside a PDF for background.

data, _ := os.ReadFile("report.pdf")
hits, _ := rustpdf.FindText(data, "Invoice", false)
for _, h := range hits {
	fmt.Printf("page %d: %q at (%.1f, %.1f) %.1fx%.1f\n",
		h.Page, h.Text, h.X, h.Y, h.Width, h.Height)
}

Render a page to an image licensed

Rasterize a page to a PNG image. A native Rust renderer (built on tiny-skia, with no headless browser) interprets the page content stream, painting real glyph outlines, vector graphics, images, color and transparency. Page rendering is a Pro feature; page_count is free.

data, _ := os.ReadFile("report.pdf")
n, _ := rustpdf.PageCount(data)
fmt.Printf("%d page(s)\n", n)
png, _ := rustpdf.RenderPageToPng(data, 0, 150.0)
os.WriteFile("page1.png", png, 0o644)

Enums

PdfaLevel

Align

VerticalAnchor

VerticalAlign

StampSpace

ImageAnchor

AFRelationship

Encryption

FacturxProfile

Error handling

Every failing native call returns an *Error carrying the Status (PdfStatus) code and the library's last-error message. License failures (missing/expired/forged token, or a feature the token doesn't grant) surface here too. Token activation failures carry the dedicated license status code (12); a gated build, sign or encrypt call instead reports that operation’s own status, with the same “requires a valid license” message. ToBytes reports Serialize = 4 and Sign reports 10. Note that Save (which writes a file) maps every failure, including a gated feature, to IO = 3 rather than 4, so match on the message rather than assuming 4 for serialization errors. Use errors.As to inspect the code.

import "errors"

doc, _ := rustpdf.New()
defer doc.Close()
_ = doc.Pdfa()
_ = doc.SetInfo(rustpdf.Info{Title: "x"})
_ = doc.AddPage()
if err := doc.Save("out.pdf"); err != nil {
	var pe *rustpdf.Error
	if errors.As(err, &pe) {
		fmt.Printf("failed: status=%d: %s\n", pe.Status, pe.Message)
		// e.g. status=3 (IO): feature 'pdfa' requires a valid license
			// (doc.ToBytes() would report status=4, Serialize)
	}
}

Utilities