typst

Python bindings to the typst <https://github.com/typst/typst>, a new markup-based typesetting system that is powerful and easy to learn.

Installation

pip install typst

Usage

import datetime
import typst


# Compile `hello.typ` to PDF and save as `hello.pdf`
typst.compile("hello.typ", output="hello.pdf")

# Compile `hello.typ` to PNG and save as `hello.png`
typst.compile("hello.typ", output="hello.png", format="png", ppi=144.0)

# Or pass `hello.typ` content as bytes
with open("hello.typ", "rb") as f:
    typst.compile(f.read(), output="hello.pdf")

# Or return PDF content as bytes
pdf_bytes = typst.compile("hello.typ")

# Use a fixed creation timestamp for reproducible PDFs
timestamp = datetime.datetime.fromtimestamp(0, datetime.timezone.utc)
pdf_bytes = typst.compile("hello.typ", timestamp=timestamp)

# Also for svg
svg_bytes = typst.compile("hello.typ", format="svg")

# Typst 0.15 minifies PDF, SVG, and HTML by default; pass pretty=True for
# human-readable export output.
svg_bytes = typst.compile("hello.typ", format="svg", pretty=True)

# Multiple compatible PDF standards can be requested at once.
pdf_bytes = typst.compile("hello.typ", pdf_standards=["a-2a", "ua-1"])

# For multi-page export (the template is the same as the typst cli)
images = typst.compile("hello.typ", output="hello{n}.png", format="png")

# Or use Compiler class to avoid reinitialization
compiler = typst.Compiler()
compiler.compile(input="hello.typ", format="png", ppi=144.0)

# Query something
import json

values = json.loads(typst.query("hello.typ", "<note>", field="value", one=True))

# Or use Typst's newer eval-style query expression
values = json.loads(typst.eval("hello.typ", "query(<note>).first().value"))

Packages

Use package_path to point Typst at a local package directory and package_cache_path to control where downloaded @preview packages are cached:

import typst

pdf = typst.compile(
    "main.typ",
    package_path="vendor",
    package_cache_path="vendor",
)

Passing values

You can pass values to the compiled Typst file with the sys_inputs argument. For example:

import json
import typst

persons = [{"name": "John", "age": 35}, {"name": "Xoliswa", "age": 45}]
sys_inputs = {"persons": json.dumps(persons)}

typst.compile(input="main.typ", output="ages.pdf", sys_inputs=sys_inputs)

The following example shows how the passed data can be used in a Typst file.

#let persons = json(bytes(sys.inputs.persons))

#for person in persons [
#person.name is #person.age years old. \
]

API reference

Python binding to typst

class typst.Compiler(input=None, root=None, font_paths=Ellipsis, ignore_system_fonts=False, sys_inputs=Ellipsis, package_path=None, package_cache_path=None)

A typst compiler

compile(input=None, output=None, format=None, ppi=None, sys_inputs=Ellipsis, pdf_standards=Ellipsis, root=None, timestamp=None, pretty=False)

Compile a typst file to PDF

compile_with_warnings(input=None, output=None, format=None, ppi=None, sys_inputs=Ellipsis, pdf_standards=Ellipsis, root=None, timestamp=None, pretty=False)

Compile a typst file and return both result and warnings

eval(expression, format=None, pretty=False, root=None)

Evaluate a Typst expression

query(selector, field=None, one=False, format=None, root=None)

Query a typst document

class typst.FontInfo

Immutable information about a single font variant

family

The font family name

index

The index of the font in its collection (0 if not a collection)

path

The file path of the font, or None for embedded fonts

stretch

The font stretch ratio (0.5-2.0)

style

The font style: “normal”, “italic”, or “oblique”

weight

The font weight (100-900)

exception typst.TypstError

exception typst.TypstWarning

typst.compile(input, output=None, root=None, font_paths=Ellipsis, ignore_system_fonts=False, format=None, ppi=None, sys_inputs=Ellipsis, pdf_standards=Ellipsis, package_path=None, timestamp=None, pretty=False, package_cache_path=None)

Compile a typst document

typst.compile_with_warnings(input, output=None, root=None, font_paths=Ellipsis, ignore_system_fonts=False, format=None, ppi=None, sys_inputs=Ellipsis, pdf_standards=Ellipsis, package_path=None, timestamp=None, pretty=False, package_cache_path=None)

Compile a typst file and return both result and warnings

typst.eval(input, expression, format=None, pretty=False, root=None, font_paths=Ellipsis, ignore_system_fonts=False, sys_inputs=Ellipsis, package_path=None, package_cache_path=None)

Evaluate a Typst expression

typst.query(input, selector, field=None, one=False, format=None, root=None, font_paths=Ellipsis, ignore_system_fonts=False, sys_inputs=Ellipsis, package_path=None, package_cache_path=None)

Query a typst document