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.

Executive Summary

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 information on this page is complemented comprehensive example implementations, which are available in the ‘examples’ directories of our GitHub repositories for pdfjs-viewer-pyside6 and pdfjs-viewer-pyqt6.

Which Package Should You Use?

Features

Installation

pip install pdfjs-viewer-pyside6

pip install pdfjs-viewer-pyside6[qt-print]

pip install pdfjs-viewer-pyqt6

pip install pdfjs-viewer-pyqt6[qt-print]

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,
    print_parallel_pages=4
)
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,
    print_parallel_pages=4
)
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)

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,
        },
        "stability": {
            "safer_mode": True,
            "disable_webgl": 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}}
)

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

All Configurable Options

Complete reference of all configuration options available:

License & Dependencies

Package Licensing

Bundled Dependencies

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