This class is for PDF only.

  • New in v1.21.0

This class represents a utility which can output various document types supported by PyMuPDF.

In PyMuPDF only used for outputting PDF documents whose pages are populated by Story DOMs.

Using DocumentWriter also for other document types might happen in the future.

Method / Attribute

Short Description


start a new output page


finish the current output page


flush pending output and close the file

Class API

class DocumentWriter#
__init__(self, path, options=None)#

Create a document writer object, passing a Python file pointer or a file path. Options to use when saving the file may also be passed.

This class can also be used as a Python context manager.

  • path

    the output file. This may be a string file name, or any Python file pointer.


    By using a io.BytesIO() object as file pointer, a document writer can create a PDF in memory. Subsequently, this PDF can be re-opened for input and be further manipulated. This technique is used by several example scripts in Stories recipes.

  • options (str) – specify saving options for the output PDF. Typical are “compress” or “clean”. More possible values may be taken from help output of the mutool convert CLI utility.


Start a new output page of a given dimension.


mediabox (rect_like) – a rectangle specifying the page size. After this method, output operations may write content to the page.


Finish a page. This flushes any pending data and appends the page to the output document.


Close the output file. This method is required for writing any pending data.

For usage examples consult the section of Story.

This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at or contact Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States for further information.

Discord logo