{"id":8746,"library":"typst","title":"Typst","description":"Typst is a Python binding to the Rust-based Typst typesetting system, designed as a modern, powerful, and easy-to-learn alternative to LaTeX. The `typst` library allows Python applications to programmatically compile Typst source files or content into various output formats such as PDF, PNG, and SVG. It boasts fast compile times due to incremental compilation and provides friendly error messages. The library is actively maintained, with version 0.14.8 currently available, and frequent releases.","status":"active","version":"0.14.8","language":"en","source_language":"en","source_url":"https://github.com/messense/typst-py","tags":["typesetting","pdf","compiler","rust-bindings","markup","documentation"],"install":[{"cmd":"pip install typst","lang":"bash","label":"Install Typst"}],"dependencies":[],"imports":[{"note":"The primary module for direct compilation functions.","symbol":"typst","correct":"import typst"},{"note":"Use the Compiler class for reusable instances to avoid reinitialization overhead.","symbol":"Compiler","correct":"from typst import Compiler"}],"quickstart":{"code":"import typst\nimport os\n\ntypst_content = \"\"\"\n#set page(width: 200pt, height: auto, margin: 1in)\n#set text(font: \"New Computer Modern\", fill: black)\n\n= Hello, Typst from Python!\n\nThis is a document compiled using the `typst` Python library.\n\n#let data = (\n  (\"Item\", \"Value\"),\n  (\"First\", 100),\n  (\"Second\", 200),\n)\n\n#table(\n  columns: 2,\n  align: (center, right),\n  stroke: .5pt,\n  ..data.map(row => row.map(cell => if cell is str { strong(cell) } else { repr(cell) }))\n)\n\n#figure(\n  image(\"https://typst.app/assets/typst-logo.png\", width: 50%),\n  caption: [The Typst logo.], \n)\n\"\"\"\n\n# Compile to PDF and save to a file\ntry:\n    pdf_bytes = typst.compile(typst_content.encode('utf-8'))\n    output_path = \"output.pdf\"\n    with open(output_path, \"wb\") as f:\n        f.write(pdf_bytes)\n    print(f\"Successfully compiled to {output_path}\")\nexcept typst.TypstError as e:\n    print(f\"Typst compilation error: {e.message}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n\n# Using the Compiler class for multiple compilations\ncompiler = typst.Compiler()\ntry:\n    png_bytes = compiler.compile(typst_content.encode('utf-8'), format=\"png\", ppi=144.0)\n    output_path_png = \"output.png\"\n    with open(output_path_png, \"wb\") as f:\n        f.write(png_bytes)\n    print(f\"Successfully compiled to {output_path_png}\")\nexcept typst.TypstError as e:\n    print(f\"Typst compilation error for PNG: {e.message}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred during PNG compilation: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Consult 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`.","message":"Typst 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.","severity":"breaking","affected_versions":"0.14.0 and later"},{"fix":"Upgrade `typst` to version 0.14.2 or later (`pip install --upgrade typst`) to address the security vulnerability.","message":"Typst 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.","severity":"breaking","affected_versions":"0.14.0, 0.14.1"},{"fix":"Pass 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.","message":"When 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'.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure all necessary `#import` statements are present at the top of every Typst file that directly utilizes the imported elements.","message":"In 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Inspect 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.","cause":"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.","error":"RuntimeError: Typst compilation failed: failed to compile: ... (diagnostic messages)"},{"fix":"Install the library using pip: `pip install typst`.","cause":"The Python `typst` library has not been installed or is not accessible in the current Python environment.","error":"ModuleNotFoundError: No module named 'typst'"},{"fix":"Ensure 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) { ... }`.","cause":"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.","error":"Error: expected expression\n╭─[/main.typ:X:Y]\n│ X │ for i in \n───╯\nError: expected semicolon or line break\n╭─[/main.typ:Z:W]\n│ Z │ (1, 2, 3) { \n────╯"},{"fix":"Verify 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()`.","cause":"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).","error":"Typst compilation error: failed to compile: error: unknown label 'my-label'"}]}