⏾ Concept Map

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

Document - PyMuPDF documentation#Document.insert_pdf

insert_pdf(docsrc, ﹡, from_page=-1, to_page=-1, start_at=-1, rotate=-1, links=True, annots=True, widgets=True, join_duplicates=False, show_progress=0, final=1)

PDF only: Copy the page range [from_page, to_page] (including both) of PDF document docsrc into the current one. Inserts will start with page number start_at. Value -1 indicates default values. All pages thus copied will be rotated as specified. Links, annotations and widgets can be excluded in the target, see below. All page numbers are 0-based.

Parameters:
  • docsrc (Document) – An opened PDF Document which must not be the current document. However, it may refer to the same underlying file.
  • from_page (int) – First page number in docsrc. Default is zero.
  • to_page (int) – Last page number in docsrc to copy. Defaults to last page.
  • start_at (int) – First copied page, will become page number start_at in the target. Default -1 appends the page range to the end. If zero, the page range will be inserted before current first page.
  • rotate (int) – All copied pages will be rotated by the provided value (degrees, integer multiple of 90).
  • links (bool) – Choose whether (internal and external) links should be included in the copy. Default is True. Named links (LINK_NAMED) and internal links to outside the copied page range are always excluded.
  • annots (bool) – choose whether annotations should be included in the copy.
  • widgets (bool) – choose whether annotations should be included in the copy. If True and at least one of the source pages contains form fields, the target PDF will be turned into a Form PDF (if not already being one).
  • join_duplicates (bool) – (New in version 1.25.5) Choose how to handle duplicate root field names in the source pages. This parameter is ignored if widgets=False. Default is False which will add unifying strings to the name of those source root fields which have a duplicate in the target. For instance, if “name” already occurs in the target, the source widget’s name will be changed to “name[text]” with a suitably chosen string “text”. If True, root fields with duplicate names in source and target will be converted to so-called “Kids” of a “Parent” object (which lists all kid widgets in a PDF array). This will effectively turn those kids into instances of the “same” widget: if e.g. one of the kids is changed, then all its instances will automatically inherit this change – no matter on which page they happen to be displayed.
  • show_progress (int) – (new in v1.17.7) specify an interval size greater zero to see progress messages on sys.stdout. After each interval, a message like Inserted 30 of 47 pages. will be printed.
  • final (int) – (new in v1.18.0) controls whether the list of already copied objects should be dropped after this method, default True. Set it to 0 except for the last one of multiple insertions from the same source PDF. This saves target file size and speeds up execution considerably.
Note:
  • This is a page-based method. Document-level information of source documents is therefore mostly ignored. Examples include Optional Content, Embedded Files, StructureElem, table of contents, page labels, metadata, named destinations (and other named entries) and some more.
  • If from_page > to_page, pages will be copied in reverse order. If 0 <= from_page == to_page, then one page will be copied.
  • docsrc TOC entries will not be copied. It is easy however, to recover a table of contents for the resulting document. Look at the examples below and at program join.py in the examples directory: it can join PDF documents and at the same time piece together respective parts of the tables of contents.

Printed 2026-10-17.

(echo:: @ ᯤ)