Skip to main content

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, PHP, Go, Ruby, and Dart.
  • Powerful typesetting: 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

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.

Metadata

Release files for oicana 0.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oicana 0.10.0
File Size Uploaded Provenance Actions
oicana-0.10.0.tar.gz 16.6 kB With provenance Details for oicana-0.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for oicana 0.10.0
File Interpreter ABI Platform Actions
oicana-0.10.0-py3-none-any.whl Python 3 none any Details for oicana-0.10.0-py3-none-any.whl

Total release size: 32.1 kB

Release files / oicana-0.10.0.tar.gz

Download URL oicana-0.10.0.tar.gz
Size 16.6 kB
Tags Source
SHA-256 checksum
How to use checksums
d2fcc13ab3ccf03cd3cabe07c19ffaa31871b3230efb609757f36e8b7270f99d
BLAKE2b-256 checksum
How to use checksums
2c92ace7dc715630a2d461f34ca61637c67155f15f921fd8cc6e70691c9ad532
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / oicana-0.10.0-py3-none-any.whl

Download URL oicana-0.10.0-py3-none-any.whl
Size 15.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
274fafcf93450331da8f650c379872663c7ff38e34efbecf0a5a7b98cf2a833c
BLAKE2b-256 checksum
How to use checksums
bbfe39e85440c01d098b85c57e4be35ed17937baf1cc859e586a2503b77e530a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Security for oicana 0.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for oicana-0.10.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.10.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page