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

# Adding link annotations to a PDF document

Adding link annotations to PDFs programmatically enables teams to automate document navigation, build interactive table of contents systems, and implement cross-referencing workflows. Whether you’re creating navigable documentation, building multipage reports with internal links, implementing automated bookmarking systems, or creating user guides with jump-to-section functionality, link annotations provide precise control over clickable areas and navigation targets. Link annotations can point to specific pages within a document at exact coordinates, enabling fine-grained navigation control for complex documents.

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

## How Nutrient helps you achieve this

Nutrient Python SDK handles PDF link annotation structures and destination management. With the SDK, you don’t need to worry about:

- Parsing link annotation dictionaries and action structures

- Managing destination arrays and coordinate transformations

- Handling named destinations and action chains

- Complex annotation border styles and appearance properties

Instead, Nutrient provides an API that handles all the complexity behind the scenes, letting you focus on your business logic.

## Complete implementation

Below is a complete working example that demonstrates adding internal link annotations to a PDF. The following lines set up the Python application. The import statements bring in all necessary classes from the Nutrient SDK:

```python

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

```

The `main()` function defines the entry point that will contain the link annotation creation logic. The `Document.open()` call opens the PDF document. The [context manager](https://docs.python.org/3/reference/datamodel.html#context-managers) syntax ensures the document is automatically closed when you’re done, preventing resource leaks. The following code creates a PDF editor, accesses the page collection, ensures at least one page exists by adding a letter-size page (612×792 points) if the document is empty, and retrieves the annotation collection from the first page:

```python

def main():
    try:
        with Document.open("input.pdf") as document:
            editor = PdfEditor.edit(document)
            pages = editor.page_collection

            if pages.count == 0:
                pages.add(612.0, 792.0)

            page = pages.first
            annotations = page.annotation_collection

```

## Adding a link to another page

The following code adds a new page to the document and creates a link annotation at coordinates (50, 600) with dimensions of 200×20 points. The `add_link()` method creates a clickable rectangular area on the first page. Link annotations define clickable regions and may be visually subtle or invisible unless you add visible cues such as nearby text, borders, or shapes. The `set_destination()` method configures the link’s navigation target with three parameters: the destination page index in this SDK example (`2`), the x-coordinate on the destination page (0.0, left edge), and the y-coordinate (792.0, top of page in points). When users click the link area, their PDF viewer navigates to the configured destination. Verify click behavior in your target viewer.

```python

            pages.add(612.0, 792.0)

            page_link = annotations.add_link(
                50.0, 600.0, 200.0, 20.0  # x, y, width, height

            )
            page_link.set_destination(2, 0.0, 792.0)

```

## Adding multiple navigation links

The following code demonstrates creating a table of contents navigation system with three clickable links. First, two additional pages are added to the document to provide navigation targets. Then three link annotations are created at vertically stacked positions (550, 520, 490 on the y-axis), each with dimensions 150×20 points. Each link is configured with `set_destination()` to navigate to a different page (2, 3, and 4 respectively), all targeting the top-left corner (0, 792). The 30-point vertical spacing between links accommodates typical text line heights for labels like “Chapter 1,” “Chapter 2,” etc. This pattern is commonly used for interactive table of contents or navigation menus in multipage documents:

```python

            pages.add(612.0, 792.0)
            pages.add(612.0, 792.0)

            link1 = annotations.add_link(
                50.0, 550.0, 150.0, 20.0  # x, y, width, height

            )
            link1.set_destination(2, 0.0, 792.0)

            link2 = annotations.add_link(
                50.0, 520.0, 150.0, 20.0  # x, y, width, height

            )
            link2.set_destination(3, 0.0, 792.0)

            link3 = annotations.add_link(
                50.0, 490.0, 150.0, 20.0  # x, y, width, height

            )
            link3.set_destination(4, 0.0, 792.0)

```

## Modifying a link destination

Existing link annotations can be reconfigured by calling `set_destination()` with new parameters. The following code demonstrates two modification patterns. The first call changes `link3` to navigate to page 2 at coordinates (100, 500), providing precise scroll positioning for fine-grained navigation control. The second call changes `link2` to navigate to page 4 while passing `None` for the x and y coordinates, which instructs the PDF viewer to use its default scroll behavior (typically fitting the page to the window). Using `None` coordinates is useful when the exact viewing position is less important than reaching the destination page:

```python

            # Change link3 to point to page 2 with specific coordinates

            link3.set_destination(2, 100.0, 500.0)

            # Change link2 to point to page 4, letting the viewer choose scroll position

            link2.set_destination(4, None, None)

```

The final code block saves the document with all link annotations and closes the editor. The try-except block handles potential errors using `NutrientException`:

```python

            editor.save_as("output.pdf")
            editor.close()
    except NutrientException as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    main()

```

## Conclusion

The link annotation workflow consists of several key operations:

1. Open the document and create an editor.

2. Access the page collection and ensure at least one page exists.

3. Retrieve the annotation collection for the target page.

4. Add pages to the document to create navigation targets.

5. Create link annotations with `add_link()` specifying clickable rectangular areas (add visible cues such as text, borders, or shapes if needed).

6. Configure link destinations with `set_destination()` specifying destination page index and coordinates, and verify behavior in your target viewer.

7. Create multiple links for table of contents navigation with vertically stacked positioning.

8. Modify existing link destinations by calling `set_destination()` with new parameters.

9. Use `None` coordinates to let the PDF viewer determine scroll positioning automatically.

10. Save and close the editor.

Nutrient handles link annotation dictionary structures, destination array formatting, and coordinate transformation calculations so you don’t need to understand PDF link annotation specifications or manage action chains manually. The link annotation system provides precise control over clickable areas and navigation targets, enabling interactive document navigation for reports, manuals, and multipage documentation.
---

## Related pages

- [Adding a custom page to a PDF document](/guides/python/editor/add-custom-page-to-pdf.md)
- [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 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)