The PdfMerger Class

class pypdf.PdfMerger(strict: bool = False, fileobj: Union[Path, str, IO] = '')

Bases: object

Initialize a PdfMerger object.

PdfMerger merges multiple PDFs into a single PDF. It can concatenate, slice, insert, or any combination of the above.

See the functions merge() (or append()) and write() for usage information.

Parameters

• strict – Determines whether user should be warned of all problems and also causes some correctable problems to be fatal. Defaults to False.

• fileobj – Output file. Can be a filename or any kind of file-like object.

merge(page_number: Optional[int] = None, fileobj: Union[None, Path, str, IO, PdfReader] = None, outline_item: Optional[str] = None, pages: Optional[Union[str, PageRange, Tuple[int, int], Tuple[int, int, int], List[int]]] = None, import_outline: bool = True, position: Optional[int] = None) → None

Merge the pages from the given file into the output file at the specified page number.

Parameters

• page_number – The page number to insert this file. File will be inserted after the given number.

• fileobj – A File Object or an object that supports the standard read and seek methods similar to a File Object. Could also be a string representing a path to a PDF file. None as an argument is deprecated.

• outline_item – Optionally, you may specify an outline item (previously referred to as a ‘bookmark’) to be applied at the beginning of the included file by supplying the text of the outline item.

• pages –

  can be a PageRange

  or a (start, stop[, step]) tuple to merge only the specified range of pages from the source document into the output document. Can also be a list of pages to merge.

  import_outline: You may prevent the source document’s

  outline (collection of outline items, previously referred to as ‘bookmarks’) from being imported by specifying this as False.

append(fileobj: Union[str, IO, PdfReader, Path], outline_item: Optional[str] = None, pages: Union[None, PageRange, Tuple[int, int], Tuple[int, int, int], List[int]] = None, import_outline: bool = True) → None

Identical to the merge() method, but assumes you want to concatenate all pages onto the end of the file instead of specifying a position.

Parameters

• fileobj – A File Object or an object that supports the standard read and seek methods similar to a File Object. Could also be a string representing a path to a PDF file.

• outline_item – Optionally, you may specify an outline item (previously referred to as a ‘bookmark’) to be applied at the beginning of the included file by supplying the text of the outline item.

• pages – can be a PageRange or a (start, stop[, step]) tuple to merge only the specified range of pages from the source document into the output document. Can also be a list of pages to append.

• import_outline – You may prevent the source document’s outline (collection of outline items, previously referred to as ‘bookmarks’) from being imported by specifying this as False.

write(fileobj: Union[Path, str, IO]) → None

Write all data that has been merged to the given output file.

Parameters

fileobj – Output file. Can be a filename or any kind of file-like object.

close() → None

Shut all file descriptors (input and output) and clear all memory usage.

add_metadata(infos: Dict[str, Any]) → None

Add custom metadata to the output.

Parameters

infos – a Python dictionary where each key is a field and each value is your new metadata. An example is {'/Title': 'My title'}

addMetadata(infos: Dict[str, Any]) → None

Use add_metadata() instead.

Deprecated since version 1.28.0.

setPageLayout(layout: typing_extensions.Literal[/NoLayout, /SinglePage, /OneColumn, /TwoColumnLeft, /TwoColumnRight, /TwoPageLeft, /TwoPageRight]) → None

Use set_page_layout() instead.

Deprecated since version 1.28.0.

set_page_layout(layout: typing_extensions.Literal[/NoLayout, /SinglePage, /OneColumn, /TwoColumnLeft, /TwoColumnRight, /TwoPageLeft, /TwoPageRight]) → None

Set the page layout.

Parameters

layout – The page layout to be used

Valid layout arguments

/NoLayout	Layout explicitly not specified
/SinglePage	Show one page at a time
/OneColumn	Show one column at a time
/TwoColumnLeft	Show pages in two columns, odd-numbered pages on the left
/TwoColumnRight	Show pages in two columns, odd-numbered pages on the right
/TwoPageLeft	Show two pages at a time, odd-numbered pages on the left
/TwoPageRight	Show two pages at a time, odd-numbered pages on the right

setPageMode(mode: typing_extensions.Literal[/UseNone, /UseOutlines, /UseThumbs, /FullScreen, /UseOC, /UseAttachments]) → None

Use set_page_mode() instead.

Deprecated since version 1.28.0.

set_page_mode(mode: typing_extensions.Literal[/UseNone, /UseOutlines, /UseThumbs, /FullScreen, /UseOC, /UseAttachments]) → None

Set the page mode.

Parameters

mode – The page mode to use.

Valid mode arguments

/UseNone	Do not show outline or thumbnails panels
/UseOutlines	Show outline (aka bookmarks) panel
/UseThumbs	Show page thumbnails panel
/FullScreen	Fullscreen view
/UseOC	Show Optional Content Group (OCG) panel
/UseAttachments	Show attachments panel

find_outline_item(outline_item: Dict[str, Any], root: Optional[List[Union[Destination, List[Union[Destination, List[Destination]]]]]] = None) → Optional[List[int]]

find_bookmark(outline_item: Dict[str, Any], root: Optional[List[Union[Destination, List[Union[Destination, List[Destination]]]]]] = None) → Optional[List[int]]

Deprecated since version 2.9.0: Use find_outline_item() instead.

add_outline_item(title: str, page_number: ~typing.Optional[int] = None, parent: ~typing.Union[None, ~pypdf.generic._data_structures.TreeObject, ~pypdf.generic._base.IndirectObject] = None, color: ~typing.Optional[~typing.Tuple[float, float, float]] = None, bold: bool = False, italic: bool = False, fit: ~pypdf.generic._fit.Fit = <pypdf.generic._fit.Fit object>, pagenum: ~typing.Optional[int] = None) → IndirectObject

Add an outline item (commonly referred to as a “Bookmark”) to this PDF file.

Parameters

• title – Title to use for this outline item.

• page_number – Page number this outline item will point to.

• parent – A reference to a parent outline item to create nested outline items.

• color – Color of the outline item’s font as a red, green, blue tuple from 0.0 to 1.0

• bold – Outline item font is bold

• italic – Outline item font is italic

• fit – The fit of the destination page.

addBookmark(title: str, pagenum: int, parent: ~typing.Union[None, ~pypdf.generic._data_structures.TreeObject, ~pypdf.generic._base.IndirectObject] = None, color: ~typing.Optional[~typing.Tuple[float, float, float]] = None, bold: bool = False, italic: bool = False, fit: typing_extensions.Literal[/Fit, /XYZ, /FitH, /FitV, /FitR, /FitB, /FitBH, /FitBV] = '/Fit', *args: ~typing.Union[~pypdf.generic._base.NumberObject, ~pypdf.generic._base.NullObject, float]) → IndirectObject

Deprecated since version 1.28.0: Use add_outline_item() instead.

add_bookmark(title: str, pagenum: int, parent: ~typing.Union[None, ~pypdf.generic._data_structures.TreeObject, ~pypdf.generic._base.IndirectObject] = None, color: ~typing.Optional[~typing.Tuple[float, float, float]] = None, bold: bool = False, italic: bool = False, fit: typing_extensions.Literal[/Fit, /XYZ, /FitH, /FitV, /FitR, /FitB, /FitBH, /FitBV] = '/Fit', *args: ~typing.Union[~pypdf.generic._base.NumberObject, ~pypdf.generic._base.NullObject, float]) → IndirectObject

Deprecated since version 2.9.0: Use add_outline_item() instead.

addNamedDestination(title: str, pagenum: int) → None

Deprecated since version 1.28.0: Use add_named_destination() instead.

add_named_destination(title: str, page_number: Optional[int] = None, pagenum: Optional[int] = None) → None

Add a destination to the output.

Parameters

• title – Title to use

• page_number – Page number this destination points at.