PDF.js Viewer for Qt (PySide6 / PyQt6)

Production-ready, embeddable PDF viewer widgets for PySide6 and PyQt6 applications, powered by Mozilla's PDF.js with basic annotation support.

Introduction

The PDF.js Viewer packages provides extensive PDF viewing and basic annotation capabilities for Qt-based Python applications. Available in two variants—pdfjs-viewer-pyside6 (LGPL) and pdfjs-viewer-pyqt6 (GPL)—these packages offer identical APIs with different licensing to accommodate both open-source and proprietary use cases.

The packages are lightweight wrappers around the PDF.js reference implementation. With extensive configuration options, individual features of the viewer can be enabled or disabled according to your needs. In addition, the packages provide a connection between the viewer and Qt, allowing it to be controlled through function calls. They also expose signals that enable the main application to react to events occurring within the viewer.

The quick‑start guide on this page is supplemented by comprehensive example implementations, which can be found in the examples directories of the GitHub repositories for pdfjs-viewer-pyside6 and pdfjs-viewer-pyqt6.

Visit my Youtube Channel to explore additional open‑source projects and gain insights into ongoing developments. The channel offers a steady look at practical implementations, background details, and new ideas that may support your own work.

If these packages save you time and effort and you’d like to support / sponsor my projects, 🍕 buy me a pizza (or one every month…) — every bite helps fuel more code.

Which Package Should You Use?

What's New in v1.1.0

Breaking Changes

• Python 3.8 and 3.9 no longer supported - Upgrade to Python 3.10+
• print_parallel_pages deprecated - Setting is ignored; printing is always sequential

Features

Installation

pip install pdfjs-viewer-pyside6

pip install pdfjs-viewer-pyqt6

Quick Start

from PySide6.QtWidgets import QApplication, QMainWindow
from pdfjs_viewer import PDFViewerWidget

app = QApplication([])
window = QMainWindow()
window.resize(1024, 768)

# Create viewer
viewer = PDFViewerWidget()
viewer.load_pdf("document.pdf")
# or show blank viewer 
# viewer.show_blank_page()
# Note: PDF.js loads a demo file if you don't load a PDF or show a blank page!

# Connect signals
viewer.pdf_loaded.connect(lambda meta: print(f"Loaded: {meta['filename']}"))
viewer.pdf_saved.connect(lambda data, path: print(f"Saved to {path}"))

window.setCentralWidget(viewer)
window.show()
app.exec()

from PyQt6.QtWidgets import QApplication, QMainWindow
from pdfjs_viewer import PDFViewerWidget

app = QApplication([])
window = QMainWindow()
window.resize(1024, 768)

# Create viewer
viewer = PDFViewerWidget()
viewer.load_pdf("document.pdf")
# or show blank viewer 
# viewer.show_blank_page()
# Note: PDF.js loads a demo file if you don't load a PDF or show a blank page!

# Connect signals
viewer.pdf_loaded.connect(lambda meta: print(f"Loaded: {meta['filename']}"))
viewer.pdf_saved.connect(lambda data, path: print(f"Saved to {path}"))

window.setCentralWidget(viewer)
window.show()
app.exec()

Viewer Options

Control how PDFs are displayed when loaded:

# Open at specific page with custom zoom
viewer.load_pdf("document.pdf", page=5, zoom="page-width")

# Open with bookmarks sidebar visible
viewer.load_pdf("document.pdf", pagemode="bookmarks")

# Combine multiple options
viewer.load_pdf(
    "document.pdf",
    page=10,
    zoom=150,          # 150% zoom
    pagemode="thumbs"  # Show thumbnails
)

# Open at specific page with custom zoom
viewer.load_pdf("document.pdf", page=5, zoom="page-width")

# Open with bookmarks sidebar visible
viewer.load_pdf("document.pdf", pagemode="bookmarks")

# Combine multiple options
viewer.load_pdf(
    "document.pdf",
    page=10,
    zoom=150,          # 150% zoom
    pagemode="thumbs"  # Show thumbnails
)

Supported options:

• page: Page number to open (1-indexed)
• zoom: Named ("page-width", "page-height", "page-fit", "auto") or numeric (10-1000)
• pagemode: Sidebar state - "none", "thumbs", "bookmarks", "attachments"
• nameddest: Named destination to navigate to

API Reference

PDFViewerWidget

Main widget class for viewing PDFs.

Methods

Signals

All signals developers can listen to:

Configuration

Print Handling

The viewer supports three print handling modes:

from pdfjs_viewer import PDFViewerWidget, PDFViewerConfig, PrintHandler

# SYSTEM mode (default) - Open PDF in OS default application
config = PDFViewerConfig(print_handler=PrintHandler.SYSTEM)
viewer = PDFViewerWidget(config=config)

# QT_DIALOG mode - a basic print dialog
config = PDFViewerConfig(
    print_handler=PrintHandler.QT_DIALOG,
    print_dpi=300,
    print_fit_to_page=True
)
viewer = PDFViewerWidget(config=config)

# EMIT_SIGNAL mode (custom handling)
config = PDFViewerConfig(print_handler=PrintHandler.EMIT_SIGNAL)
viewer = PDFViewerWidget(config=config)
viewer.print_data_ready.connect(my_custom_print_handler)

from pdfjs_viewer import PDFViewerWidget, PDFViewerConfig, PrintHandler

# SYSTEM mode (default) - Open PDF in OS default application
config = PDFViewerConfig(print_handler=PrintHandler.SYSTEM)
viewer = PDFViewerWidget(config=config)

# QT_DIALOG mode - a basic print dialog
config = PDFViewerConfig(
    print_handler=PrintHandler.QT_DIALOG,
    print_dpi=300,
    print_fit_to_page=True
)
viewer = PDFViewerWidget(config=config)

# EMIT_SIGNAL mode (custom handling)
config = PDFViewerConfig(print_handler=PrintHandler.EMIT_SIGNAL)
viewer = PDFViewerWidget(config=config)
viewer.print_data_ready.connect(my_custom_print_handler)

import pdfjs_viewer

def main():
    pdfjs_viewer.freeze_support()   # required for QT_DIALOG in frozen builds
    app = QApplication(sys.argv)
    ...

Unsaved Changes Handling

Protect users from accidentally losing annotation work with the unsaved_changes_action configuration:

from pdfjs_viewer import PDFViewerWidget, ConfigPresets

# Enable unsaved changes protection
config = ConfigPresets.annotation()
config.features.unsaved_changes_action = "prompt"
viewer = PDFViewerWidget(config=config)

# Check programmatically before closing
if viewer.has_unsaved_changes():
    viewer.handle_unsaved_changes()  # Shows save/discard dialog

# Or connect to the annotation_modified signal
viewer.annotation_modified.connect(
    lambda: print("Annotations modified")
)

from pdfjs_viewer import PDFViewerWidget, ConfigPresets

# Enable unsaved changes protection
config = ConfigPresets.annotation()
config.features.unsaved_changes_action = "prompt"
viewer = PDFViewerWidget(config=config)

# Check programmatically before closing
if viewer.has_unsaved_changes():
    viewer.handle_unsaved_changes()  # Shows save/discard dialog

# Or connect to the annotation_modified signal
viewer.annotation_modified.connect(
    lambda: print("Annotations modified")
)

Global Stability Configuration

For maximum stability in embedded systems or crash-prone environments, apply Chromium flags before creating QApplication:

import sys
from pdfjs_viewer.stability import configure_global_stability

# Apply stability flags (call BEFORE QApplication!)
configure_global_stability(
    disable_gpu=True,
    disable_webgl=True,
    disable_gpu_compositing=True,
    disable_unnecessary_features=True,
)

# Now create your application
from PySide6.QtWidgets import QApplication
app = QApplication(sys.argv)

from pdfjs_viewer import PDFViewerWidget
viewer = PDFViewerWidget()

import sys
from pdfjs_viewer.stability import configure_global_stability

# Apply stability flags (call BEFORE QApplication!)
configure_global_stability(
    disable_gpu=True,
    disable_webgl=True,
    disable_gpu_compositing=True,
    disable_unnecessary_features=True,
)

# Now create your application
from PyQt6.QtWidgets import QApplication
app = QApplication(sys.argv)

from pdfjs_viewer import PDFViewerWidget
viewer = PDFViewerWidget()

This sets environment variables that Chromium reads at startup, providing stability improvements at the application level. Safe per-widget defaults (isolated profile, no cache, no WebGL) are always applied automatically.

Configuration Presets

7 pre-configured presets for common use cases:

from pdfjs_viewer import PDFViewerWidget, ConfigPresets, PrintHandler

# Simple preset usage
viewer = PDFViewerWidget(preset="readonly")

# Customize a preset
viewer = PDFViewerWidget(
    preset="readonly",
    customize={
        "features": {
            "save_enabled": True,
            "freetext_enabled": True,
            "ink_enabled": True,
        },
        "security": {
            "allow_external_links": True,
            "block_remote_content": False,
        },
    }
)

# Hybrid approach (recommended)
config = ConfigPresets.annotation()
config.print_handler = PrintHandler.EMIT_SIGNAL
config.features.stamp_enabled = False
viewer = PDFViewerWidget(config=config)

from pdfjs_viewer import PDFViewerWidget, ConfigPresets, PrintHandler

# Simple preset usage
viewer = PDFViewerWidget(preset="readonly")

# Customize a preset
viewer = PDFViewerWidget(
    preset="readonly",
    customize={
        "features": {
            "save_enabled": True,
            "freetext_enabled": True,
            "ink_enabled": True,
        },
        "security": {
            "allow_external_links": True,
            "block_remote_content": False,
        },
    }
)

# Hybrid approach (recommended)
config = ConfigPresets.annotation()
config.print_handler = PrintHandler.EMIT_SIGNAL
config.features.stamp_enabled = False
viewer = PDFViewerWidget(config=config)

All Configurable Options

Complete reference of all configuration options available:

config = PDFViewerConfig(
    security=PDFSecurityConfig(
        custom_csp="default-src 'self'; script-src 'self' 'unsafe-inline'; img-src 'self' data: https://trusted.com"
    )
)

License & Dependencies

Package Licensing

Runtime Dependencies

Print Dependencies

These packages are installed automatically and used for the PrintHandler.QT_DIALOG print mode:

These dependencies are included in the default installation — no extra install step is needed.

License Comparison: PySide6 vs PyQt6

PySide6 (LGPL):

• ✅ Can be used in proprietary applications
• ✅ No need to open-source your application
• ⚠️ Must keep Qt libraries as external shared libraries (not statically linked)
• ⚠️ Users must be able to replace PySide6/Qt libraries

PyQt6 (GPL):

• ⚠️ Must license your application under GPL v3
• ⚠️ Must provide source code to users
• ⚠️ Must include GPL v3 license and copyright notices
• ✅ No library replacement requirements

Additional Resources

• LGPL v3.0 Full Text
• GPL v3.0 Full Text
• Qt Licensing Information
• Choose a License Guide