Install & Compatibility
Where this runs
tested against v0.14.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.2s · import 0.001s · 81MB
79MB installed
● package 79MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
typst
✓ import typst
The primary module for direct compilation functions.
Compiler
✓ from typst import Compiler
Use the Compiler class for reusable instances to avoid reinitialization overhead.
This quickstart demonstrates compiling Typst content from a Python string into a PDF file, and also using the `Compiler` class to output a PNG. It includes basic text, a table, and an image from a URL within the Typst source. Error handling for `typst.TypstError` is also shown.
import typst
import os
typst_content = """
#set page(width: 200pt, height: auto, margin: 1in)
#set text(font: "New Computer Modern", fill: black)
= Hello, Typst from Python!
This is a document compiled using the `typst` Python library.
#let data = (
("Item", "Value"),
("First", 100),
("Second", 200),
)
#table(
columns: 2,
align: (center, right),
stroke: .5pt,
..data.map(row => row.map(cell => if cell is str { strong(cell) } else { repr(cell) }))
)
#figure(
image("https://typst.app/assets/typst-logo.png", width: 50%),
caption: [The Typst logo.],
)
"""
# Compile to PDF and save to a file
try:
pdf_bytes = typst.compile(typst_content.encode('utf-8'))
output_path = "output.pdf"
with open(output_path, "wb") as f:
f.write(pdf_bytes)
print(f"Successfully compiled to {output_path}")
except typst.TypstError as e:
print(f"Typst compilation error: {e.message}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
# Using the Compiler class for multiple compilations
compiler = typst.Compiler()
try:
png_bytes = compiler.compile(typst_content.encode('utf-8'), format="png", ppi=144.0)
output_path_png = "output.png"
with open(output_path_png, "wb") as f:
f.write(png_bytes)
print(f"Successfully compiled to {output_path_png}")
except typst.TypstError as e:
print(f"Typst compilation error for PNG: {e.message}")
except Exception as e:
print(f"An unexpected error occurred during PNG compilation: {e}")
typst --version
Debug
Known issues
breakingTypst 0.14.0 introduced several minor breaking changes in the underlying Typst language and compiler. Notable changes include labels, link URLs, and font lists no longer accepting empty values, `pdf.embed` being renamed to `pdf.attach`, and some bibliography styles being renamed. Documents written for older Typst versions might require adjustments.fixConsult the official Typst changelog for 0.14.0 and newer versions. Update your Typst source files according to the new syntax and API, for example, replace `pdf.embed` with `pdf.attach`.
affects: 0.14.0 and later
breakingTypst versions 0.14.0 and 0.14.1 of the underlying Rust compiler (used by `typst-py`) contained a memory handling vulnerability in the WebAssembly runtime used for plugins. Although considered hard to exploit, an upgrade is recommended.fixUpgrade `typst` to version 0.14.2 or later (`pip install --upgrade typst`) to address the security vulnerability.
affects: 0.14.0, 0.14.1
gotchaWhen compiling multi-file Typst projects, the `typst.compile()` function or `Compiler.compile()` method expects a dictionary where keys are filenames (e.g., 'main.typ', 'lib.typ') and values are their content as bytes. The main entry file should typically be keyed as 'main' or 'main.typ'.fixPass a dictionary `{'main.typ': b'main_content', 'other.typ': b'other_content'}` to `compile()` instead of a single string or path for multi-file projects. affects: All
gotchaIn Typst documents, imports are not global. If a package or module (e.g., `#import "@preview/physica:0.9.5": *`) is needed in multiple `.typ` files (e.g., chapters of a larger document), it must be explicitly imported in *each* file where its components are used. This differs from global import behaviors in some other languages.fixEnsure all necessary `#import` statements are present at the top of every Typst file that directly utilizes the imported elements.
affects: All
Errors
Common errors & fixes
RuntimeError: Typst compilation failed: failed to compile: ... (diagnostic messages)
This generic runtime error indicates a problem within the Typst source code being compiled, such as syntax errors, missing files referenced in the Typst document, or other Typst language-specific issues.
fixInspect the `e.message` (if catching `typst.TypstError`) or the full error output for specific diagnostic messages from the Typst compiler. Correct the Typst syntax, ensure all referenced files are present and correctly specified, and check for Typst breaking changes if recently upgraded.
ModuleNotFoundError: No module named 'typst'
The Python `typst` library has not been installed or is not accessible in the current Python environment.
fixInstall the library using pip: `pip install typst`.
Error: expected expression
╭─[/main.typ:X:Y]
│ X │ for i in
───╯
Error: expected semicolon or line break
╭─[/main.typ:Z:W]
│ Z │ (1, 2, 3) {
────╯
This Typst parser error occurs when there's a line break immediately after the `in` keyword in a `for` loop, before the iterable is specified. The parser expects the iterable on the same line or separated by an explicit semicolon.
fixEnsure the iterable follows the `in` keyword on the same line, or explicitly terminate the `in` line with a semicolon if the iterable must start on a new line. Example: `#for i in (1, 2, 3) { ... }` or `#for i in; (1, 2, 3) { ... }`. Typst compilation error: failed to compile: error: unknown label 'my-label'
This error occurs when a label (e.g., `#label("my-label")`) is referenced (e.g., `@my-label`) within a Typst document, but the label itself is either not defined, misspelled, or not yet available in the compilation scope (e.g., in a separate file that hasn't been properly included/imported).
fixVerify that the label is correctly defined and spelled in the Typst source. For multi-file projects, ensure that the file defining the label is accessible and compiled as part of the project, often by passing all relevant files in the dictionary input to `typst.compile()`.
Upgrade
Version history
0.14.9latest on PyPI · released May 14, 2026
Audit
Dependencies
No dependency data recorded yet.