⏾ Concept Map

Document.save() ⚬｜Documentation｜1st｜20261017135122-00-⌔

Document - PyMuPDF documentation#Document.save

save(outfile, garbage=0, clean=False, deflate=False, deflate_images=False, deflate_fonts=False, incremental=False, ascii=False, expand=0, linear=False, pretty=False, no_new_id=False, encryption=PDF_ENCRYPT_NONE, permissions=-1, owner_pw=None, user_pw=None, use_objstms=0, compression_effort=0, raise_on_repair=False)

PDF documents are saved in their current state.

Non-PDF documents are saved in PDF format. (new in v1.28.0)

Parameters:
  • outfile (str , Path , fp) – The file path, pathlib.Path or file object to save to. A file object must have been created before via open(...) or io.BytesIO(). Choosing io.BytesIO() is similar to Document.tobytes() below, which equals the getvalue() output of an internally created io.BytesIO().
  • garbage (int) – Do garbage collection. Positive values exclude “incremental”.
    - 0 = none
    - 1 = remove unused (unreferenced) objects.
    - 2 = in addition to 1, compact the xref table.
    - 3 = in addition to 2, merge duplicate objects.
    - 4 = in addition to 3, check stream objects for duplication. This may be slow because such data are typically large.
  • clean (bool) – Clean and sanitize content streams [1]. Corresponds to “mutool clean -sc”.
  • deflate (int) – Deflate (compress) uncompressed streams. See: Compressing Files for full details on this parameter.
  • deflate_images (bool) – (new in v1.18.3) Deflate (compress) uncompressed image streams [4].
  • deflate_fonts (bool) – (new in v1.18.3) Deflate (compress) uncompressed fontfile streams [4].
  • incremental (bool) – Only save changes to the PDF. Excludes “garbage” and “linear”. Can only be used if outfile is a string or a pathlib.Path and equal to Document.name. Cannot be used for files that are decrypted or repaired and also in some other cases. To be sure, check Document.can_save_incrementally(). If this is false, saving to a new file is required.
  • ascii (bool) – convert binary data to ASCII.
  • expand (int) – Decompress objects. Generates versions that can be better read by some other programs and will lead to larger files.
    - 0 = none
    - 1 = images
    - 2 = fonts
    - 255 = all
  • linear (bool) – Save a linearised version of the document. This option creates a file format for improved performance for Internet access. Excludes “incremental” and “use_objstms”.
  • pretty (bool) – Prettify the document source for better readability. PDF objects will be reformatted to look like the default output of Document.xref_object().
  • no_new_id (bool) – Suppress the update of the file’s /ID field. If the file happens to have no such field at all, also suppress creation of a new one. Default is False, so every save will lead to an updated file identification.
  • permissions (int) – (new in v1.16.0) Set the desired permission levels. See Document Permissions for possible values. Default is granting all.
  • encryption (int) – (new in v1.16.0) set the desired encryption method. See PDF encryption method codes for possible values.
  • owner_pw (str) – (new in v1.16.0) set the document’s owner password. (Changed in v1.18.3) If not provided, the user password is taken if provided. The string length must not exceed 40 characters.
  • user_pw (str) – (new in v1.16.0) set the document’s user password. The string length must not exceed 40 characters.
  • use_objstms (int) – (new in v1.24.0) compression option that converts eligible PDF object definitions to information that is stored in some other object’s stream data. Depending on the deflate parameter value, the converted object definitions will be compressed – which can lead to very significant file size reductions. See: Compressing Files for full details on this parameter.
  • compression_effort (int) – See: Compressing Files for full details on this parameter.
    - 0 for default
    - 1 for minimum effort.
    - 100 for maximum effort.
  • raise_on_repair (bool) – (new in v1.27.0) If true we raise an exception if the save caused a repair. This is useful because repairs can cause changes to be lost. Also see Document.repair().

Warning: The method does not check, whether a file of that name already exists, will hence not ask for confirmation, and overwrite the file. It is your responsibility as a programmer to handle this.

Note: File size reduction

  1. Use the save options like garbage=3|4, deflate=True, use_objstms=True|1. Do not touch the default values expand=False|0, clean=False|0, incremental=False|0, linear=False|0. This is a “lossless” file size reduction. There is a convenience version of this method with these values set by default, Document.ez_save() – please see below.
  • “Lossy” file size reduction in essence must give up something with respect to images, like (a) remove all images (b) replace images by their grayscale versions (c) reduce image resolutions. Find examples in the PyMuPDF Utilities “replace-image” folder.

See: Compressing Files for more.

Printed 2026-10-17.

(echo:: @ ᯤ)