Oicana for Python

Generate PDFs in Python without a headless browser.

Python teams generating PDFs usually pick between a headless browser, HTML-to-PDF engines that fight page breaks and fonts, or low-level libraries that turn every layout into code. The abandoned wkhtmltopdf still shows up in production stacks.

Oicana compiles PDFs in process through native bindings instead. You design documents as Typst templates, load them once at startup, and render them from JSON in single-digit milliseconds. No browser process, no per-document fees, no document data leaving your infrastructure.

Free for noncommercial use. Commercial use is free for 30 days, then needs a per-application subscription with unlimited seats.

Installation

pip install oicana     # or: uv add oicana

Wheels are published for Linux, macOS, and Windows on Python 3.9 and newer.

Quick start

import json
from pathlib import Path

from oicana import Template

template_bytes = Path("invoice-0.1.0.zip").read_bytes()

with Template(template_bytes) as template:
    pdf = template.export(
        json_inputs={"invoice": json.dumps({
            "number": "2026-001",
            "customer": "Acme GmbH",
            "total": "€1,190.00",
        })},
    )

Path("invoice.pdf").write_bytes(pdf)

export returns the PDF bytes. export_png and export_svg produce the other formats, and Template.export_once renders a one-off template without registering it. The Template context manager frees native resources on exit.

What a template looks like

Templates are plain Typst projects. A typst.toml manifest names the entrypoint and declares the inputs your application passes in:

[package]
name = "invoice"
version = "0.1.0"
entrypoint = "main.typ"

[tool.oicana]
manifest_version = 1

[[tool.oicana.inputs]]
type = "json"
key = "invoice"
development = "invoice.json"

The entrypoint, main.typ, reads those inputs through the Oicana Typst package and lays out the document:

#import "@preview/oicana:0.2.0": setup

#let read-project-file(path) = read(path, encoding: none)
#let (input, oicana-image, oicana-config) = setup(read-project-file)

#set document(title: "Invoice", date: datetime.today())

= Invoice #input.invoice.number

Billed to: #input.invoice.customer

*Total: #input.invoice.total*

The development value lets the template preview with real data in any Typst editor. oicana pack turns the directory into invoice-0.1.0.zip, the archive every Oicana integration loads.

The Oicana CLI does the packing, so a layout change ships as a new asset, not a code change.

Running in a web service

Load the template once at startup and export per request; afterwards there is no file I/O on the hot path. The native calls release the GIL, so exports from several worker threads run in parallel.

Full type hints ship with the package, so Template, CompilationMode, ExportFormat, and the input types autocomplete and type-check.

Why Oicana

• Runs in your infrastructure: PDFs are generated inside your own application. No data is sent to a third-party service.
• Multi-platform: the same template works in the browser, Node.js, C#, Java, Rust, Python, and PHP.
• Powerful layouting: templates have all of Typst, including its package ecosystem.
• Performant: a warmed up template renders a PDF in single-digit milliseconds.
• AI and version control ready: templates are text files. They live next to your code, and AI can help write them.
• No proprietary format: templates are plain Typst projects. The Typst compiler is open source.

Where to go next

• Python / FastAPI getting started guide: from an empty project to a PDF endpoint
• Open source FastAPI example: blob inputs, error handling, and a preview endpoint
• PDF generation in Python: the shorter overview
• How Oicana compares: against headless browsers, PDF libraries, and hosted APIs

Licensing

Oicana is source-available under the PolyForm Noncommercial License 1.0.0 and free for noncommercial use. Commercial use is free for 30 days; see pricing for subscriptions, or write to hello@oicana.com.