---
title: "Adding a custom page to a PDF document | Nutrient Python SDK"
canonical_url: "https://www.nutrient.io/guides/python/editor/add-custom-page-to-pdf/"
md_url: "https://www.nutrient.io/guides/python/editor/add-custom-page-to-pdf.md"
last_updated: "2026-06-09T10:32:42.848Z"
description: "How to add a custom page to a PDF using Nutrient Python SDK."
---

# Adding a custom page to a PDF document

Use page insertion to control document structure in generated PDFs.

Common use cases include:

- Inserting cover pages for invoices

- Adding divider pages between legal sections

- Appending signature pages to forms

- Inserting note pages into educational documents

- Adding title or section pages in generated reports

This guide shows how to:

- Insert a page at a specific index (zero-based)

- Define custom page dimensions in points (`1 inch = 72 points`)

- Export the final document as PDF

[Download sample](https://www.nutrient.io/downloads/samples/python/add-custom-page-to-pdf.zip)

## How Nutrient helps

Nutrient Python SDK handles page collection management, insertion, and document conversion.

The SDK handles:

- PDF page structure and internal page tree dictionaries

- Page dimensions and coordinate transformations for different page sizes

- Document conversion from Word, Excel, and PowerPoint to PDF

- Page indexing and insertion position validation

## Complete implementation

This example inserts a custom page and exports the result to PDF:

```python

from nutrient_sdk import Document
from nutrient_sdk import PdfEditor
from nutrient_sdk import NutrientException

```

## Opening a document

Open the input document in a [context manager](https://docs.python.org/3/reference/datamodel.html#context-managers) so Python closes resources after processing.

In this sample, you open a Word file (`.docx`). The SDK also supports:

- PDF files

- Word binary files (`.doc`)

- PowerPoint files (`.pptx`) and PowerPoint binary files (`.ppt`)

- Excel files (`.xlsx`) and Excel binary files (`.xls`)

- Input streams

```python

def main():
    try:
        with Document.open("input.docx") as document:

```

## Creating a PDF editor and accessing pages

Create a `PdfEditor` and get the page collection.

Use this object to insert, remove, or reorder pages:

```python

            editor = PdfEditor.edit(document)
            pages = editor.page_collection

```

## Adding custom pages

Insert a page with `pages.insert(index, width, height)`.

Parameters:

- `index`: zero-based insertion point (`0` inserts before the first page)

- `width`: page width in points

- `height`: page height in points

In this example:

- `pages.insert(0, 500.0, 800.0)` inserts the page at the beginning.

- `500.0 × 800.0` points is a custom page size.

Common page sizes:

- US Letter: `612 × 792` points

- A4: `595 × 842` points

- Legal: `612 × 1008` points

```python

            pages.insert(0, 500.0, 800.0)

```

## Saving and exporting

Save changes, close the editor, and export the document as PDF.

The `except` block catches `NutrientException` for processing failures:

```python

            editor.save()
            editor.close()

            document.export_as_pdf("output.pdf")
            print("Successfully added page and exported PDF")
    except NutrientException as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    main()

```

## Error handling

The SDK raises `NutrientException` when an operation fails.

Common failure scenarios include:

- The input file can’t be read due to file system permissions, path errors, or file locking by another process

- Document data is corrupted or uses an unsupported file format, preventing proper parsing

- Insufficient system memory for loading large documents or performing format conversion

- Invalid page insertion index (negative or beyond document bounds) causing index out of range errors

- Invalid page dimensions (zero or negative width/height values) preventing page creation

- PDF export failures due to incompatible document features or encoding issues

In production code:

- Catch `NutrientException`.

- Return a clear error message.

- Log exception details for debugging.

## Conclusion

To add custom pages to a PDF workflow:

1. Open the source document with a [context manager](https://docs.python.org/3/reference/datamodel.html#context-managers).

2. Create an editor with `PdfEditor.edit(document)`.

3. Get pages with `editor.page_collection`.

4. Insert a page with `pages.insert(index, width, height)`.

5. Save and close the editor.

6. Export the result with `document.export_as_pdf()`.

7. Catch `NutrientException` to handle failures.

For broader document workflows, refer to the [Python SDK guides](https://www.nutrient.io/guides/python.md) for format conversion and advanced editing.

Download [this ready-to-use sample package](https://www.nutrient.io/downloads/samples/python/add-custom-page-to-pdf.zip), fully configured to help you explore the page manipulation capabilities.
---

## Related pages

- [Adding annotations to a PDF document](/guides/python/editor/add-annotations-to-pdf.md)
- [Adding invisible digital signatures to a PDF document](/guides/python/editor/add-invisible-signature-to-pdf.md)
- [Adding interactive form fields to a PDF document](/guides/python/editor/add-form-fields-to-pdf.md)
- [Adding free text annotations to a PDF document](/guides/python/editor/add-freetext-annotations-to-pdf.md)
- [Adding link annotations to a PDF document](/guides/python/editor/add-link-annotations-to-pdf.md)
- [Adding redaction annotations to a PDF document](/guides/python/editor/add-redaction-annotations-to-pdf.md)
- [Adding shape annotations to a PDF document](/guides/python/editor/add-shape-annotations-to-pdf.md)
- [Adding stamp annotations to a PDF document](/guides/python/editor/add-stamp-annotations-to-pdf.md)
- [Adding sticky note annotations to a PDF document](/guides/python/editor/add-sticky-note-annotations-to-pdf.md)
- [Adding text markup annotations to a PDF document](/guides/python/editor/add-text-markup-annotations-to-pdf.md)
- [Advanced digital signature workflows](/guides/python/editor/advanced-digital-signatures.md)
- [Adding visible digital signatures to a PDF document](/guides/python/editor/add-visible-signature-to-pdf.md)
- [Detecting and adding form fields to a PDF document](/guides/python/editor/detect-and-add-form-fields.md)
- [Editing PDF form fields](/guides/python/editor/editing-pdf-form-fields.md)
- [Editing PDF metadata with Nutrient Python SDK](/guides/python/editor/editing-pdf-metadata.md)
- [Managing PDF page order](/guides/python/editor/manage-pdf-page-order.md)
- [Merging PDFs](/guides/python/editor/merge-pdf-into-other-pdf.md)
- [Nutrient Python SDK editor guides](/guides/python/editor.md)
- [Filling PDF form fields](/guides/python/editor/fill-pdf-form.md)