Stirling-PDF User Guide

Stirling-PDF is a self-hosted, privacy-first PDF manipulation toolkit that runs entirely on your own hardware. Version 2.9.2 delivers over 50 distinct PDF operations through a modern web interface, a REST API, and an optional desktop application -- all without sending a single page to an external server.

This guide covers every operation Stirling-PDF provides, how to install and configure it for your environment, and how to solve the problems you will encounter along the way. Configuration details, deployment architectures, monitoring, and security hardening live in the companion Admin Guide.

1. Quick Start

Get Stirling-PDF running in under two minutes with Docker:

docker run -d \
  -p 8080:8080 \
  --name stirling-pdf \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:fat

Open your browser to http://localhost:8080. The home screen presents every available tool organized by category. Click any tool, upload your PDF, adjust options, and download the result.

Tip

The :fat image includes all dependencies (LibreOffice, Tesseract OCR, fonts). If you only need basic PDF operations and want a smaller image, use :ultra-lite instead -- it skips LibreOffice and OCR but still handles merging, splitting, rotating, watermarking, and most security operations.

2. Installation

2.1 Docker (Recommended)

Docker is the primary deployment method. Three image variants are available:

Images are available from Docker Hub and the project's own registry at docker.stirlingpdf.com/stirlingtools/stirling-pdf.

Important

The :fat image requires at least 6 GB of memory allocated to Docker. On Docker Desktop (Windows/macOS), check Settings, then Resources, then Memory and increase it if necessary. Insufficient memory causes silent crashes during LibreOffice-based conversions.

Docker Compose (production setup)

Create a docker-compose.yml file:

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:fat
    ports:
      - "8080:8080"
    volumes:
      - ./stirling/data:/usr/share/tessdata:rw
      - ./stirling/config:/configs:rw
      - ./stirling/logs:/logs:rw
      - ./stirling/customFiles:/customFiles:rw
      - ./stirling/pipeline:/pipeline:rw
    environment:
      DISABLE_ADDITIONAL_FEATURES: "false"
      DOCKER_ENABLE_SECURITY: "false"
      SYSTEM_DEFAULTLOCALE: en-US
      UI_APPNAME: Stirling-PDF
      SYSTEM_MAXFILESIZE: "100"
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    deploy:
      resources:
        limits:
          memory: 6G

Start the stack:

docker compose up -d

Warning

Always create the volume directories before starting the container (mkdir -p ./stirling/{data,config,logs,customFiles,pipeline}). If Docker creates them as root-owned directories, the container may fail to write configuration or log files.

Volume Mounts

Docker Run (quick start)

docker run -d \
  -p 8080:8080 \
  -v ./stirling/data:/usr/share/tessdata:rw \
  -v ./stirling/config:/configs:rw \
  -v ./stirling/logs:/logs:rw \
  --name stirling-pdf \
  --restart unless-stopped \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:fat

Unified Container Modes

The container supports three operating modes via the MODE environment variable:

Split-mode deployment example:

services:
  stirling-backend:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:fat
    environment:
      MODE: BACKEND
      BACKEND_INTERNAL_PORT: "8081"
    ports:
      - "8081:8081"

  stirling-frontend:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:fat
    environment:
      MODE: FRONTEND
      VITE_API_BASE_URL: "http://stirling-backend:8081"
    ports:
      - "8080:8080"

Setting User/Group IDs

Control the process ownership inside the container with PUID, PGID, and UMASK:

environment:
  PUID: "1000"
  PGID: "1000"
  UMASK: "022"

This ensures files written to mounted volumes have the correct ownership on the host.

2.2 Desktop Application (Tauri)

Stirling-PDF is available as a native desktop application for Windows, macOS, and Linux. The desktop app bundles the full Stirling-PDF backend and frontend into a single installable package.

Windows:

1. Download the .msi installer from the GitHub Releases page
2. Run the installer -- it also registers a PDF thumbnail handler for Windows Explorer
3. Launch from the Start Menu

macOS:

1. Download the .dmg from GitHub Releases
2. Drag to Applications
3. On first launch, right-click then select Open to bypass Gatekeeper

Linux:

1. Download the .AppImage or .deb package from GitHub Releases
2. For AppImage: chmod +x Stirling-PDF*.AppImage && ./Stirling-PDF*.AppImage
3. For deb: sudo dpkg -i stirling-pdf*.deb

The desktop app opens a native window with the same web UI. All processing happens locally on your machine.

2.3 Building from Source

Requirements:

• Java 21 or later (JDK, not JRE)
• Node.js (for building the React frontend)
• Gradle (wrapper included in repository)

git clone https://github.com/Stirling-Tools/Stirling-PDF.git
cd Stirling-PDF
./gradlew build
java -jar app/core/build/libs/*.jar

The application starts on port 8080 by default.

For the frontend only (development):

cd frontend
npm install
npm run dev

2.4 Verifying the Installation

After starting Stirling-PDF by any method, verify it is running:

curl http://localhost:8080/api/v1/info/status

Expected response: UP

Open http://localhost:8080 in a browser. You should see the Stirling-PDF home page with all available tools.

3. Understanding the Interface

3.1 Home Page

The home page displays all available PDF tools as cards organized by functional group. Each card shows the tool name and a brief description. Click any card to open that tool.

The top navigation bar provides:

• Home -- return to the tool grid
• Search -- find tools by name or description
• Pipeline -- access the automation pipeline builder
• Settings -- application configuration (when security is enabled, this requires login)

3.2 Tool Pages

Every tool page follows a consistent layout:

1. File upload area -- drag and drop PDFs or click to browse. Some tools accept multiple files.
2. Options panel -- tool-specific settings (page ranges, quality levels, formats, etc.)
3. Submit button -- processes the file(s) with the selected options
4. Download -- the result is automatically downloaded when processing completes

3.3 Page Selection Syntax

Many tools require you to specify which pages to operate on. Stirling-PDF supports a powerful page selection syntax:

Operators:

• OR: , or | -- union of page sets
• AND: & -- intersection of page sets
• NOT: ! -- exclusion (negate a page set)
• Parentheses: () -- group expressions for precedence

3.4 API Access

Every tool is accessible via REST API at /api/v1/. Interactive API documentation is available at:

http://localhost:8080/swagger-ui/index.html

The Swagger UI lets you explore all endpoints, view request/response schemas, and test operations directly from the browser.

Example API call -- merge two PDFs:

curl -X POST "http://localhost:8080/api/v1/general/merge-pdfs" \
  -F "fileInput=@file1.pdf" \
  -F "fileInput=@file2.pdf" \
  -o merged.pdf

When SECURITY_CUSTOMGLOBALAPIKEY is set, include the API key in requests:

curl -X POST "http://localhost:8080/api/v1/general/merge-pdfs" \
  -H "X-API-Key: your-api-key-here" \
  -F "fileInput=@file1.pdf" \
  -F "fileInput=@file2.pdf" \
  -o merged.pdf

4. Page Operations

Page operations restructure, reorder, and transform the pages within a PDF without altering page content.

4.1 Merge PDFs

Combine multiple PDF files into a single document.

How to use:

1. Navigate to Page Operations > Merge PDFs
2. Upload two or more PDF files
3. Drag to reorder the files in the desired sequence
4. Click Merge
5. Download the combined PDF

API:

curl -X POST "http://localhost:8080/api/v1/general/merge-pdfs" \
  -F "fileInput=@chapter1.pdf" \
  -F "fileInput=@chapter2.pdf" \
  -F "fileInput=@chapter3.pdf" \
  -o complete-book.pdf

Tip

When merging many files, the order in the upload list determines the order in the output. Use drag-and-drop in the web UI to rearrange before merging.

4.2 Split Pages

Divide a PDF into multiple files, each containing a specified range of pages.

How to use:

1. Navigate to Page Operations > Split Pages
2. Upload a PDF
3. Enter page numbers or ranges where splits should occur (e.g., 1,5,10 splits into pages 1-4, 5-9, and 10-end)
4. Click Split
5. Download the resulting ZIP containing individual PDFs

API:

curl -X POST "http://localhost:8080/api/v1/general/split-pages" \
  -F "fileInput=@document.pdf" \
  -F "pages=1,5,10" \
  -o split-pages.zip

4.3 Remove Pages

Delete specific pages from a PDF.

How to use:

1. Navigate to Page Operations > Remove Pages
2. Upload a PDF
3. Enter the pages to remove using page selection syntax (e.g., 2,5,8-10)
4. Click Remove
5. Download the PDF with those pages removed

API:

curl -X POST "http://localhost:8080/api/v1/general/remove-pages" \
  -F "fileInput=@document.pdf" \
  -F "pagesToDelete=2,5,8-10" \
  -o cleaned.pdf

4.4 Rearrange Pages

Reorder pages within a PDF by specifying the new page sequence.

How to use:

1. Navigate to Page Operations > Rearrange Pages
2. Upload a PDF
3. Specify the new order (e.g., 3,1,2,5,4 reorders so page 3 comes first)
4. Use the visual page editor to drag and drop page thumbnails into the desired sequence
5. Click Rearrange

The visual editor shows thumbnails of every page and supports drag-and-drop reordering, which is the easiest way to work with documents that have many pages.

4.5 Rotate PDF

Rotate all pages or specific pages by 90, 180, or 270 degrees.

How to use:

1. Navigate to Page Operations > Rotate PDF
2. Upload a PDF
3. Select rotation angle: 90 degrees, 180 degrees, or 270 degrees clockwise
4. Optionally specify which pages to rotate (default: all)
5. Click Rotate

API:

curl -X POST "http://localhost:8080/api/v1/general/rotate-pdf" \
  -F "fileInput=@document.pdf" \
  -F "angle=90" \
  -o rotated.pdf

4.6 Multi-Page Layout

Arrange multiple PDF pages onto a single page (N-up printing). Useful for creating handouts or reducing paper usage.

How to use:

1. Navigate to Page Operations > Multi-Page Layout
2. Upload a PDF
3. Select the layout: 2-up, 4-up, 9-up, 16-up, or custom grid
4. Choose page ordering (left-to-right then top-to-bottom, or alternatives)
5. Click Submit

Common configurations:

4.7 Booklet Imposition

Rearrange pages for booklet-style printing. After double-sided printing and folding, pages appear in the correct reading order.

How to use:

1. Navigate to Page Operations > Booklet Imposition
2. Upload a PDF
3. The tool reorders pages for saddle-stitch binding
4. Print the output double-sided, flip on short edge, then fold in half

For a 16-page document, the tool rearranges pages so that when printed double-sided on 4 sheets and folded, the pages read 1, 2, 3, ... 16 in order.

4.8 Scale Pages

Resize all pages to a different paper size or scale by percentage.

How to use:

1. Navigate to Page Operations > Scale Pages
2. Upload a PDF
3. Select target page size (A4, Letter, Legal, A3, etc.) or enter a custom scale percentage
4. Choose scaling behavior: fit content within the new size, fill the page, or stretch
5. Click Submit

4.9 Crop

Remove margins or crop pages to a specific region.

How to use:

1. Navigate to Page Operations > Crop
2. Upload a PDF
3. Define the crop box by specifying margins to remove (top, bottom, left, right) in points or percentages
4. Optionally apply the crop to specific pages only using page selection syntax
5. Click Crop

4.10 PDF to Single Page

Merge all pages of a PDF into one continuous vertical page. Useful for web-style viewing, creating scrollable documents, or preparing content for continuous-feed printing.

How to use:

1. Navigate to Page Operations > PDF to Single Page
2. Upload a PDF
3. Click Submit
4. Download the single-page result

The output is one very tall page containing all original pages stacked vertically.

4.11 Auto-Split PDF

Automatically detect and split a PDF at logical boundaries using blank pages, QR codes, or barcodes as separators.

How to use:

1. Navigate to Page Operations > Auto-Split PDF
2. Upload a PDF that contains separator pages
3. Select the split method:
   • Blank page detection -- splits at blank or near-blank pages
   • QR code -- splits when a QR code is detected on a page
   • Barcode -- splits at barcode-bearing pages
4. Configure detection sensitivity if applicable
5. Click Split
6. Download the ZIP containing the split PDFs

This is particularly useful for processing batches of scanned documents that use blank separator sheets.

4.12 Split by Size or Count

Split a PDF into chunks of a specified file size or page count.

How to use:

1. Navigate to Page Operations > Split by Size or Count
2. Upload a PDF
3. Choose split mode:
   • By page count: Enter the number of pages per output file (e.g., 10 pages each)
   • By file size: Enter the maximum size per output file (e.g., 5 MB)
4. Click Split
5. Download the ZIP of resulting files

This is useful for email attachment size limits or systems that cap individual file sizes.

4.13 Overlay PDF

Overlay one PDF on top of another. Common uses include adding a letterhead template to every page, applying a form template, or compositing two documents.

How to use:

1. Navigate to Page Operations > Overlay PDF
2. Upload the base PDF (the document to apply the overlay to)
3. Upload the overlay PDF (the template or layer to place on top)
4. Select overlay mode:
   • Overlay -- the overlay PDF renders on top of the base PDF content
   • Underlay -- the overlay PDF renders behind the base PDF content
5. Choose whether the overlay repeats (same page applied to every base page) or maps page-by-page
6. Click Submit

4.14 Split PDF by Sections

Split a PDF based on page sections -- dividing each page into regions (halves, quadrants, or custom grids) and producing separate pages for each region.

How to use:

1. Navigate to Page Operations > Split PDF by Sections
2. Upload a PDF
3. Define how to divide each page:
   • Horizontal splits (number of rows)
   • Vertical splits (number of columns)
4. Click Submit
5. Each section of each page becomes its own page in the output

This is useful for separating multi-column layouts or extracting individual panels from composite pages.

4.15 Split PDF by Chapters

Split a PDF using its existing table of contents or bookmark structure. Each top-level bookmark becomes a separate output file.

How to use:

1. Navigate to Page Operations > Split PDF by Chapters
2. Upload a PDF that contains bookmarks/outlines
3. Select the bookmark level at which to split (level 1 for top-level chapters, level 2 for sub-chapters, etc.)
4. Click Split
5. Download the ZIP containing one PDF per chapter

Note

This tool requires the PDF to have embedded bookmarks/outlines. If the PDF has no bookmarks, the split will not produce meaningful results. Use Edit Table of Contents (in Other Tools) first to add bookmarks if needed.

4.16 Add Page Numbers

Add page numbers to every page (or selected pages) of a PDF.

How to use:

1. Navigate to Page Operations > Add Page Numbers
2. Upload a PDF
3. Configure the numbering:
   • Position: top or bottom of page; left, center, or right alignment
   • Starting number: which number the first page receives
   • Font size: size of the page number text
   • Margin offset: distance from the edge of the page
4. Optionally select which pages receive numbers using page selection syntax
5. Click Submit

4.17 Extract Pages

Extract specific pages from a PDF into a new file. Unlike Remove Pages (which removes specified pages and keeps the rest), Extract Pages keeps only the specified pages.

How to use:

1. Navigate to Page Operations > Extract Pages
2. Upload a PDF
3. Enter the pages to extract using page selection syntax (e.g., 1-5, 10, 15-20, odd, !(1-3))
4. Click Extract
5. Download the PDF containing only the selected pages

5. Format Conversion

Convert PDFs to and from dozens of formats. Some conversions require LibreOffice or other dependencies available in the :fat image or via manual installation.

5.1 PDF to Image

Convert PDF pages to images in various formats.

How to use:

1. Navigate to Convert > PDF to Image
2. Upload a PDF
3. Select output format: PNG, JPEG, GIF, TIFF, BMP, or WebP
4. Set DPI/resolution:
   • 72 DPI -- screen viewing
   • 150 DPI -- standard print quality
   • 300 DPI -- high-quality print
   • 600 DPI -- professional/archival quality
5. Choose to produce one image per page or all pages in a single file
6. Click Convert

API:

curl -X POST "http://localhost:8080/api/v1/convert/pdf/img" \
  -F "fileInput=@document.pdf" \
  -F "imageFormat=png" \
  -F "dpi=150" \
  -o pages.zip

5.2 Image to PDF

Convert one or more images into a PDF document.

How to use:

1. Navigate to Convert > Image to PDF
2. Upload one or more images (PNG, JPEG, TIFF, BMP, GIF, WebP)
3. Optionally set page size and orientation
4. Arrange image order by dragging
5. Click Convert

API:

curl -X POST "http://localhost:8080/api/v1/convert/img/pdf" \
  -F "fileInput=@photo1.jpg" \
  -F "fileInput=@photo2.jpg" \
  -o photos.pdf

5.3 PDF to PDF/A

Convert a PDF to PDF/A format for long-term archival compliance. PDF/A is an ISO-standardized version of PDF designed for digital preservation.

How to use:

1. Navigate to Convert > PDF to PDF/A
2. Upload a PDF
3. Select PDF/A conformance level:
   • PDF/A-1b -- basic conformance, widest reader compatibility
   • PDF/A-2b -- adds JPEG 2000, transparency, layers
   • PDF/A-3b -- allows embedded files of any type
4. Click Convert

Note

PDF/A conversion may strip interactive elements (JavaScript, multimedia, external links) to comply with archival standards. Verify the output if your PDF contains forms or annotations that must be preserved.

5.4 File to PDF (Office Documents)

Convert DOCX, XLSX, PPTX, ODT, ODS, ODP, and other office formats to PDF using LibreOffice.

How to use:

1. Navigate to Convert > File to PDF
2. Upload a document in any supported format
3. Click Convert

Supported input formats: DOCX, DOC, XLSX, XLS, PPTX, PPT, ODT, ODS, ODP, RTF, TXT, CSV, HTML, XML, and other formats supported by LibreOffice.

Important

This feature requires LibreOffice. It is included in the :fat Docker image. If using :ultra-lite or :latest without LibreOffice installed, this conversion will not be available. Tools that require missing dependencies appear grayed out on the home page.

5.5 PDF to Word

Convert a PDF to DOCX format. The conversion preserves text content and attempts to maintain formatting, though complex layouts may not transfer perfectly.

How to use:

1. Navigate to Convert > PDF to Word
2. Upload a PDF
3. Click Convert
4. Download the .docx file

5.6 PDF to Presentation

Convert a PDF to PPTX format. Each page becomes a slide.

How to use:

1. Navigate to Convert > PDF to Presentation
2. Upload a PDF
3. Click Convert
4. Download the .pptx file

5.7 PDF to Text

Extract all text content from a PDF as a plain text file.

How to use:

1. Navigate to Convert > PDF to Text
2. Upload a PDF
3. Click Convert
4. Download the .txt file

For scanned PDFs that contain images of text rather than actual text, run OCR first (see Section 7.1) to make the text extractable.

5.8 PDF to HTML

Convert a PDF to an HTML document, preserving layout where possible.

How to use:

1. Navigate to Convert > PDF to HTML
2. Upload a PDF
3. Click Convert
4. Download the HTML file

5.9 PDF to XML

Export PDF content as structured XML.

How to use:

1. Navigate to Convert > PDF to XML
2. Upload a PDF
3. Click Convert

5.10 HTML to PDF

Convert an HTML file to PDF. The rendering engine processes CSS and produces a paginated PDF.

How to use:

1. Navigate to Convert > HTML to PDF
2. Upload an HTML file (with or without inline CSS/images)
3. Click Convert

5.11 URL to PDF

Capture a web page as a PDF by providing its URL.

How to use:

1. Navigate to Convert > URL to PDF
2. Enter the full URL of the web page (e.g., https://example.com/article)
3. Click Convert
4. Download the rendered PDF

The page is rendered as it appears in a browser, including CSS styling. JavaScript-rendered content is captured as well.

5.12 Markdown to PDF

Convert a Markdown file to a formatted PDF with proper headings, lists, code blocks, and other Markdown elements rendered visually.

How to use:

1. Navigate to Convert > Markdown to PDF
2. Upload a .md file
3. Click Convert

5.13 PDF to CSV

Extract tabular data from a PDF into CSV format. Works best with PDFs that contain clearly structured tables.

How to use:

1. Navigate to Convert > PDF to CSV
2. Upload a PDF containing tables
3. Click Convert
4. Download the .csv file

For best results, the source PDF should have clean, grid-based tables. Complex or multi-column layouts may produce less accurate results.

5.14 PDF to Markdown

Convert PDF content to Markdown format, preserving headings, lists, and basic formatting.

How to use:

1. Navigate to Convert > PDF to Markdown
2. Upload a PDF
3. Click Convert

5.15 Email to PDF (EML to PDF)

Convert email files in EML format to PDF, preserving headers, body, and formatting.

How to use:

1. Navigate to Convert > EML to PDF
2. Upload an .eml file
3. Click Convert

5.16 PDF to EPUB

Convert a PDF to EPUB format for e-readers like Kindle, Kobo, and Nook.

How to use:

1. Navigate to Convert > PDF to EPUB
2. Upload a PDF
3. Click Convert
4. Transfer the resulting .epub to your e-reader

Text-heavy PDFs (novels, articles) convert well. Image-heavy or layout-intensive PDFs may lose formatting in the EPUB conversion.

5.17 PDF to Vector and Vector to PDF

Convert between PDF and vector image formats (SVG).

PDF to Vector:

1. Navigate to Convert > PDF to Vector
2. Upload a PDF
3. Click Convert
4. Download the SVG output

Vector to PDF:

1. Navigate to Convert > Vector to PDF
2. Upload an SVG file
3. Click Convert

5.18 PDF to Video

Convert PDF pages into a video slideshow where each page is displayed for a configurable duration.

How to use:

1. Navigate to Convert > PDF to Video
2. Upload a PDF
3. Configure the duration each slide is displayed (seconds per page)
4. Click Convert

5.19 CBZ to PDF and PDF to CBZ

Convert between PDF and CBZ (Comic Book ZIP) format, commonly used for digital comic books.

CBZ to PDF:

1. Navigate to Convert > CBZ to PDF
2. Upload a .cbz file
3. Click Convert

PDF to CBZ:

1. Navigate to Convert > PDF to CBZ
2. Upload a PDF
3. Click Convert

5.20 PDF to JSON and JSON to PDF

Convert PDF structure and content to JSON representation, and reconstruct PDFs from JSON.

PDF to JSON:

1. Navigate to Convert > PDF to JSON
2. Upload a PDF
3. Click Convert

JSON to PDF:

1. Navigate to Convert > JSON to PDF
2. Upload a JSON file conforming to the expected schema
3. Click Convert

5.21 PDF to RTF

Convert a PDF to Rich Text Format, which is widely supported by word processors.

How to use:

1. Navigate to Convert > PDF to RTF
2. Upload a PDF
3. Click Convert

6. Security Operations

Protect, encrypt, sign, redact, and validate PDFs. All security operations happen locally -- no certificates, passwords, or document content leave your server.

6.1 Add Password

Encrypt a PDF with a password. You can set both a user password (required to open the document) and an owner password (required to modify permissions).

How to use:

1. Navigate to Security > Add Password
2. Upload a PDF
3. Enter the password
4. Select encryption strength (128-bit AES or 256-bit AES)
5. Optionally set separate owner and user passwords for different access levels
6. Click Encrypt

API:

curl -X POST "http://localhost:8080/api/v1/security/add-password" \
  -F "fileInput=@document.pdf" \
  -F "password=MySecurePass123" \
  -o encrypted.pdf

6.2 Remove Password

Remove password protection from a PDF. You must know the current password.

How to use:

1. Navigate to Security > Remove Password
2. Upload the encrypted PDF
3. Enter the current password
4. Click Remove
5. Download the unencrypted PDF

6.3 Change Permissions

Modify the permission flags on a PDF to control what actions readers can perform.

How to use:

1. Navigate to Security > Change Permissions
2. Upload a PDF
3. Select which permissions to allow or deny:
   • Printing (full quality or degraded)
   • Content copying and extraction
   • Document modification
   • Annotation and form editing
   • Form filling
   • Page assembly
4. Set the owner password to enforce the permissions
5. Click Apply

6.4 Add Watermark

Add a text or image watermark to PDF pages.

How to use:

1. Navigate to Security > Add Watermark
2. Upload a PDF
3. Choose watermark type:
   • Text watermark: enter the text (e.g., "CONFIDENTIAL", "DRAFT", a company name)
   • Image watermark: upload an image file
4. Configure appearance:
   • Position: center, corner, or custom coordinates
   • Rotation: typically 0 degrees (horizontal) or 45 degrees (diagonal)
   • Opacity: 0-100% (10-20% for subtle, 50-80% for visible stamps)
   • Font size: for text watermarks
5. Choose which pages to watermark (all pages or specific pages)
6. Click Apply

Tip

For a subtle "CONFIDENTIAL" watermark, set the text to light gray, 45-degree rotation, 15% opacity, and position it centered. For a visible header stamp, use 100% opacity, 0-degree rotation, and position it at the top of the page.

6.5 Certificate Signing

Digitally sign a PDF with an X.509 certificate for legal and authenticity purposes.

How to use:

1. Navigate to Security > Certificate Sign
2. Upload a PDF
3. Upload your certificate file (.p12 or .pfx format)
4. Enter the certificate password
5. Optionally configure:
   • Signature appearance (visible or invisible)
   • Signature location on the page
   • Reason for signing
6. Click Sign

6.6 Remove Certificate Signature

Remove digital certificate signatures from a PDF.

How to use:

1. Navigate to Security > Remove Certificate Sign
2. Upload a signed PDF
3. Click Remove
4. Download the unsigned version

6.7 Sanitize PDF

Remove potentially dangerous or privacy-compromising content from a PDF. This is a security-focused tool that strips elements that could pose risks.

How to use:

1. Navigate to Security > Sanitize PDF
2. Upload a PDF
3. Select what to remove:
   • Embedded JavaScript -- could execute malicious code in PDF readers
   • Embedded files and attachments -- could contain malware
   • Metadata -- author name, creation software, GPS coordinates, timestamps
   • Actions -- auto-open URLs, form submission actions, print triggers
4. Click Sanitize

Warning

Sanitization is irreversible and permanently removes selected content. Always keep a backup of the original file. Removing JavaScript will break interactive PDF forms that rely on calculated fields or validation scripts.

6.8 Timestamp PDF

Add a trusted timestamp to a PDF to provide cryptographic proof that the document existed in a specific form at a specific time. This is useful for legal compliance and intellectual property protection.

How to use:

1. Navigate to Security > Timestamp PDF
2. Upload a PDF
3. Enter the TSA (Time Stamp Authority) URL (e.g., http://timestamp.digicert.com)
4. Click Timestamp

6.9 Auto-Redact

Automatically detect and redact sensitive information using pattern matching. The tool scans for common patterns like email addresses, phone numbers, social security numbers, and credit card numbers.

How to use:

1. Navigate to Security > Auto-Redact
2. Upload a PDF
3. Select the types of information to redact:
   • Email addresses
   • Phone numbers
   • Social security numbers
   • Credit card numbers
   • Custom patterns (regular expressions)
4. Configure redaction appearance (black box, colored box, or replacement text)
5. Click Redact

6.10 Redact

Manually redact specific text or areas in a PDF. Unlike covering text with a shape, proper redaction permanently removes the underlying text data.

How to use:

1. Navigate to Security > Redact
2. Upload a PDF
3. Enter text strings to search and redact, or use the visual editor to select areas
4. Configure the redaction appearance
5. Click Apply

Caution

Redaction permanently and irreversibly removes content from the PDF. Unlike a black highlight marker (which can be removed digitally), redaction eliminates the underlying text data. Always verify redacted documents by attempting to search for the redacted terms -- no matches should be found.

6.11 Validate Signature

Check whether digital signatures in a PDF are valid and trustworthy.

How to use:

1. Navigate to Security > Validate Signature
2. Upload a signed PDF
3. The tool displays:
   • Signature status (valid/invalid/unknown)
   • Signer information
   • Certificate chain details
   • Whether the document was modified after signing

6.12 Add Stamp

Add a visual stamp to PDF pages. Stamps are opaque labels placed on top of page content, commonly used for document status indicators.

How to use:

1. Navigate to Security > Add Stamp
2. Upload a PDF
3. Choose a predefined stamp (CONFIDENTIAL, APPROVED, DRAFT, FINAL, etc.) or enter custom text
4. Configure position, size, color, and rotation
5. Select which pages receive the stamp
6. Click Apply

6.13 Unlock PDF Forms

Remove restrictions on PDF form fields, making them editable when they have been locked or flattened by form creators.

How to use:

1. Navigate to Security > Unlock PDF Forms
2. Upload a PDF with locked form fields
3. Click Unlock
4. Download the PDF with editable form fields

6.14 Verify PDF

Verify the structural integrity of a PDF file. This tool checks the PDF for conformance issues, structural errors, and potential corruption.

How to use:

1. Navigate to Security > Verify PDF
2. Upload a PDF
3. Review the verification results, which report any structural issues found

6.15 Sign (Visual Signature)

Add a handwritten-style visual signature to a PDF. This is distinct from certificate signing -- it places a visual representation of your signature on the page.

How to use:

1. Navigate to Security > Sign
2. Upload a PDF
3. Create your signature using one of three methods:
   • Draw -- use your mouse or touchscreen to draw your signature
   • Type -- type your name and select a script font
   • Upload -- upload an image of your signature (PNG with transparent background works best)
4. Position the signature on the desired page and location
5. Click Apply

7. Other Tools

7.1 OCR PDF

Apply Optical Character Recognition to make scanned PDFs searchable and text-selectable. OCR converts images of text into actual machine-readable text embedded in the PDF.

How to use:

1. Navigate to Other Tools > OCR PDF
2. Upload a scanned PDF
3. Select the document language(s) -- accuracy depends heavily on correct language selection
4. Choose OCR mode:
   • Force OCR: OCR all pages regardless of whether they already contain extractable text
   • Skip text: Only OCR pages that have no existing extractable text (faster for mixed documents)
   • Normal: Default behavior
5. Click Apply

Adding OCR Languages:

The default installation includes English. To OCR documents in other languages, add Tesseract language data files.

Using the environment variable (recommended for Docker):

environment:
  TESSERACT_LANGS: "deu,fra,spa,jpn,chi_sim,kor,ara"

The container downloads the specified language data on startup.

Manually downloading language files:

# Download German language data into the tessdata volume
wget -P ./stirling/data/ \
  https://github.com/tesseract-ocr/tessdata/raw/main/deu.traineddata

Common language codes:

Important

OCR accuracy depends heavily on selecting the correct language. For multilingual documents, specify all relevant languages. The :ultra-lite image does not include Tesseract -- OCR is unavailable on that variant.

7.2 Extract Images

Extract all embedded images from a PDF as individual image files.

How to use:

1. Navigate to Other Tools > Extract Images
2. Upload a PDF
3. Select output format (PNG or JPEG)
4. Click Extract
5. Download the ZIP containing all extracted images

Each image embedded in the PDF (photos, diagrams, logos) is extracted at its original resolution.

7.3 Update Metadata

View and modify PDF metadata fields such as title, author, subject, keywords, creator, and producer.

How to use:

1. Navigate to Other Tools > Update Metadata
2. Upload a PDF
3. The current metadata is displayed for review
4. Edit any field:
   • Title -- the document title
   • Author -- the document author
   • Subject -- a brief subject description
   • Keywords -- comma-separated keywords
   • Creator -- the application that created the original content
   • Producer -- the application that produced the PDF
5. Click Save

7.4 Flatten PDF

Flatten form fields, annotations, comments, and layers into the page content. The result is a static PDF where all interactive elements become part of the page image.

How to use:

1. Navigate to Other Tools > Flatten
2. Upload a PDF
3. Click Flatten

Flattening is commonly used:

• Before printing, to ensure annotations appear as intended
• Before sharing, to prevent form field modification
• Before applying operations that do not preserve form fields (such as certain split operations)
• To reduce file complexity

7.5 Remove Blank Pages

Detect and remove blank or near-blank pages from a PDF. Useful for cleaning up scanned documents that include separator sheets or accidental blank pages.

How to use:

1. Navigate to Other Tools > Remove Blanks
2. Upload a PDF
3. Adjust the blank detection threshold -- the sensitivity control determines how much content a page can have and still be considered "blank" (increase the threshold to catch pages with minor artifacts like scan noise)
4. Click Remove

7.6 Remove Annotations

Strip all annotations from a PDF, including comments, highlights, sticky notes, strikethroughs, underlines, ink annotations, and other markup.

How to use:

1. Navigate to Other Tools > Remove Annotations
2. Upload a PDF
3. Click Remove
4. Download the annotation-free PDF

7.7 Get PDF Info

Display comprehensive information about a PDF file.

How to use:

1. Navigate to Other Tools > Get Info on PDF
2. Upload a PDF
3. Review the information display, which includes:
   • Page count and individual page sizes
   • PDF version
   • Encryption status and method
   • Metadata (title, author, creation date, etc.)
   • Font list (embedded and referenced)
   • Producer and creator applications
   • File size and structure details

7.8 Add Attachments

Embed files as attachments within a PDF. Attached files travel with the PDF and can be extracted by the recipient.

How to use:

1. Navigate to Other Tools > Add Attachments
2. Upload a PDF
3. Upload the files you want to attach (any file type)
4. Click Add
5. Download the PDF with embedded attachments

7.9 Replace/Invert Colors

Replace or invert colors in a PDF. This tool processes the visual content of each page.

How to use:

1. Navigate to Other Tools > Replace/Invert PDF
2. Upload a PDF
3. Choose the color operation:
   • Full inversion -- inverts all colors (creates a "dark mode" version)
   • Custom color mapping -- replace specific colors with others
4. Click Apply

This is useful for creating dark-background versions of documents for comfortable screen reading, or for accessibility adjustments.

7.10 Edit Table of Contents

Add, modify, or remove the bookmark/outline structure of a PDF. Bookmarks appear as a navigable tree in PDF readers, allowing quick jumps to specific sections.

How to use:

1. Navigate to Other Tools > Edit Table of Contents
2. Upload a PDF
3. The existing bookmark tree is displayed in an editable form
4. Edit the structure:
   • Add new bookmarks with a title and target page number
   • Rename existing bookmarks
   • Delete unwanted bookmarks
   • Reorder or nest bookmarks to create a hierarchy
5. Click Save

7.11 Text Editor

Edit text directly within a PDF. This tool provides a visual editor for modifying existing text content.

How to use:

1. Navigate to Other Tools > Text Editor
2. Upload a PDF
3. Select text on the page to edit
4. Modify the text content
5. Click Save

Text editing in PDFs is inherently limited compared to word processors. Complex layout changes may not be possible, but simple text corrections (fixing typos, updating dates, changing names) work well.

7.12 Add Image

Insert an image into a PDF at a specified position and page.

How to use:

1. Navigate to Other Tools > Add Image
2. Upload a PDF
3. Upload the image to insert (PNG, JPEG, etc.)
4. Select the target page
5. Position the image by specifying coordinates or dragging in the preview
6. Adjust size and rotation as needed
7. Click Apply

7.13 Compare PDFs

Compare two PDF files side by side and highlight differences. Useful for reviewing document revisions.

How to use:

1. Navigate to Other Tools > Compare
2. Upload two PDF files (the original and the modified version)
3. View the comparison results, which highlight:
   • Added content
   • Deleted content
   • Changed content
   • Moved content

7.14 View PDF

View a PDF directly in the browser using the built-in PDF.js viewer, without needing a separate PDF reader.

How to use:

1. Navigate to Other Tools > View PDF
2. Upload a PDF
3. Use the viewer controls:
   • Page navigation
   • Zoom in/out
   • Full-text search
   • Bookmark navigation
   • Print

8. Advanced Tools

8.1 Compress PDF

Reduce PDF file size by optimizing images, removing duplicate objects, and streamlining the document structure.

How to use:

1. Navigate to Advanced > Compress PDF
2. Upload a PDF
3. Select compression level:
   • Low (1-2): Minimal quality loss, moderate size reduction
   • Medium (3-4): Balanced quality and size -- good default for most uses
   • High (5): Maximum compression, noticeable quality reduction in images
4. Click Compress
5. The output shows both original and compressed file sizes

API:

curl -X POST "http://localhost:8080/api/v1/general/compress-pdf" \
  -F "fileInput=@large-document.pdf" \
  -F "optimizeLevel=3" \
  -o compressed.pdf

8.2 Extract Image Scans

Split a scanned page containing multiple photos or documents into individual images. This is designed for flatbed scanning workflows where you scan multiple physical photos on a single pass.

How to use:

1. Navigate to Advanced > Extract Image Scans
2. Upload a PDF containing scanned pages with multiple photos/documents per page
3. The tool automatically detects individual image boundaries
4. Download the extracted, separated images

8.3 Repair PDF

Attempt to repair a corrupted or malformed PDF that fails to open correctly in PDF readers.

How to use:

1. Navigate to Advanced > Repair
2. Upload the damaged PDF
3. Click Repair
4. Download the repaired version

Not all corrupted PDFs can be repaired. The tool fixes common structural issues like broken cross-reference tables, missing end-of-file markers, and damaged object streams.

8.4 Auto-Rename

Automatically generate descriptive filenames for PDFs based on their content. The tool analyzes titles, dates, and subject matter to suggest meaningful names.

How to use:

1. Navigate to Advanced > Auto-Rename
2. Upload one or more PDFs
3. The tool analyzes each document and generates a suggested filename
4. Download the renamed files

8.5 Scanner Effect

Apply visual effects that make a digital PDF look like it was scanned from a physical copy. Adds subtle imperfections such as slight rotation, noise, reduced contrast, and border darkening.

How to use:

1. Navigate to Advanced > Scanner Effect
2. Upload a PDF
3. Adjust effect parameters:
   • Rotation randomness -- how much each page tilts (simulates manual scanning)
   • Noise level -- grain/speckle added to the image
   • Border darkening -- shadow at page edges
4. Click Apply

8.6 Adjust Contrast

Modify the contrast, brightness, and saturation of pages in a PDF. Useful for improving readability of faded scans or adjusting visual appearance.

How to use:

1. Navigate to Advanced > Adjust Contrast
2. Upload a PDF
3. Adjust the sliders:
   • Contrast -- increase to sharpen the difference between light and dark areas
   • Brightness -- increase to lighten, decrease to darken
   • Saturation -- increase for more vivid colors, decrease toward grayscale
4. Click Apply

9. Automation: Pipelines

Pipelines let you chain multiple Stirling-PDF operations into automated workflows. Instead of running each tool manually one at a time, define a sequence of operations that executes in a single step.

9.1 Creating a Pipeline

1. Navigate to Pipeline in the top navigation bar
2. Click Create New Pipeline
3. Add operations in sequence by selecting tools from the dropdown
4. Configure each operation's parameters (the same options available in each tool's individual page)
5. Save the pipeline with a descriptive name

9.2 Pipeline Structure

A pipeline consists of an ordered list of operations. Each operation specifies:

• Tool: Which Stirling-PDF operation to run
• Parameters: The configuration for that operation
• Input: Automatically connected -- the output of the previous operation feeds into the next (the initial upload feeds into the first step)

Example pipeline -- prepare a document for archival:

Example pipeline -- secure a document for distribution:

9.3 Running a Pipeline

1. Open a saved pipeline
2. Upload one or more input PDFs
3. Click Run Pipeline
4. Each operation executes in sequence, with progress shown
5. Download the final output

9.4 Pipeline API

Pipelines can be triggered via the API for integration with external systems:

curl -X POST "http://localhost:8080/api/v1/general/handleData" \
  -F "fileInput=@document.pdf" \
  -F "pipelineConfig=@my-pipeline.json" \
  -o result.pdf

9.5 Watched Folder Automation

Place pipeline configuration files in the /pipeline directory (mapped to ./stirling/pipeline on the host). Stirling-PDF can monitor this directory and automatically process files placed in designated input folders.

Tip

Combine watched-folder pipelines with cron jobs or file watchers on the host system to build fully automated document processing workflows. For example, scan a network share for incoming PDFs, route them through a standardize-and-archive pipeline, and save results to an output directory -- all without manual intervention.

10. Developer Tools

10.1 Show JavaScript

View embedded JavaScript within a PDF. This is a diagnostic tool for developers and security auditors who need to inspect what scripts are bundled inside a PDF.

How to use:

1. Navigate to Developer Tools > Show JavaScript
2. Upload a PDF
3. Any embedded JavaScript is displayed in a syntax-highlighted code viewer
4. Review the scripts for functionality or potential security issues

PDFs can contain JavaScript for form calculations, field validation, and interactive features. This tool surfaces all such scripts without executing them.

11. Configuration Reference

11.1 Environment Variables

Configure Stirling-PDF behavior through environment variables. Set these in docker-compose.yml, pass them with docker run -e, or configure them in the desktop app's settings.

Application identity:

System behavior:

Security:

Features and tools:

Performance:

Container configuration:

11.2 Settings File

Beyond environment variables, Stirling-PDF reads configuration from /configs/settings.yml inside the container. Mount a volume to /configs to persist settings across restarts:

# /configs/settings.yml
security:
  enableLogin: false
  initialLogin:
    username: admin
    password: stirling

system:
  defaultLocale: en-US
  maxFileSize: 100

ui:
  appName: "Stirling-PDF"
  homeDescription: "Your PDF tools"

11.3 Custom UI Files

The /customFiles volume mount supports customizing the UI appearance:

• Custom logos and branding images
• Additional CSS styling
• Custom HTML templates

Place files in the mounted directory and restart the container to apply changes.

11.4 Reverse Proxy Configuration

When running Stirling-PDF behind a reverse proxy, set SYSTEM_ROOTURIPATH if the application is not served at the root path.

environment:
  SYSTEM_ROOTURIPATH: "/stirling-pdf"

Nginx example:

location /stirling-pdf/ {
    proxy_pass http://stirling-pdf:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    client_max_body_size 100M;
}

Traefik label example:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.stirling.rule=Host(`pdf.example.com`)"
  - "traefik.http.services.stirling.loadbalancer.server.port=8080"

For full reverse proxy configuration details including Caddy, Apache, and advanced TLS settings, see the Admin Guide.

11.5 Authentication

Enable authentication by setting both DOCKER_ENABLE_SECURITY and SECURITY_ENABLELOGIN:

environment:
  DOCKER_ENABLE_SECURITY: "true"
  SECURITY_ENABLELOGIN: "true"

Configure initial admin credentials in settings.yml:

security:
  enableLogin: true
  initialLogin:
    username: admin
    password: change-me-immediately

Change the default password on first login. For detailed authentication configuration including OAuth and SSO, see the Admin Guide.

11.6 JVM Tuning

Two JVM profiles are available via STIRLING_JVM_PROFILE:

For additional tuning, use JAVA_CUSTOM_OPTS:

environment:
  JAVA_CUSTOM_OPTS: "-Xmx4g -Xms2g -XX:MaxMetaspaceSize=512m"

11.7 Disabling Tool Groups

Remove specific tool groups from the UI and API:

environment:
  ENDPOINTS_GROUPS_TO_REMOVE: "CLI"

This hides the specified groups from the home page and disables their API endpoints entirely.

12. Workflows and Use Cases

12.1 Digitize a Paper Archive

Goal: Convert a stack of scanned documents into searchable, compressed, archival-compliant PDFs.

1. Scan documents to PDF using any scanner
2. Upload to OCR PDF -- select the appropriate language(s)
3. Run through Remove Blank Pages to eliminate empty scanner separator pages
4. Apply Compress PDF at medium quality to reduce storage
5. Convert to PDF/A for long-term archival compliance
6. Use Auto-Rename to give files meaningful names based on detected content

Pipeline alternative: create a pipeline with steps 2-6 and batch-process the entire archive.

12.2 Prepare a Booklet for Printing

Goal: Print a document as a folded booklet on a standard printer.

1. Upload your PDF to Booklet Imposition
2. The tool reorders pages for saddle-stitch binding
3. Print the output double-sided, with "flip on short edge" selected
4. Fold the printed pages in half and staple in the center

12.3 Merge and Secure Meeting Minutes

Goal: Combine monthly meeting minutes into a single protected document.

1. Upload all monthly PDFs to Merge PDFs and reorder chronologically
2. Merge and download the combined document
3. Upload the merged file to Add Page Numbers (start from 1, bottom center)
4. Upload to Update Metadata -- set title, author, and keywords
5. Upload to Add Password -- set a strong password for distribution

12.4 Redact Sensitive Information for Public Release

Goal: Prepare documents for FOIA or public distribution by removing personal information.

1. Upload documents to Auto-Redact -- select SSN, phone, email, and credit card patterns
2. Review the output carefully to verify all sensitive content is redacted
3. Run through Flatten to ensure redactions are permanent and cannot be removed
4. Use Sanitize PDF to strip metadata that might contain sensitive information
5. Verify by opening the result and searching for redacted terms -- zero results expected

12.5 Convert a Photo Album to E-Reader Format

Goal: Turn a collection of images into an EPUB for reading on a Kindle or similar device.

1. Upload all images to Image to PDF and arrange in desired order
2. Download the combined PDF
3. Upload to PDF to EPUB
4. Transfer the .epub file to your e-reader

12.6 Standardize Documents for Legal Filing

Goal: Ensure all documents meet court filing requirements (consistent size, numbered, stamped).

1. Use Scale Pages to standardize all documents to Letter (8.5 x 11) or A4
2. Apply Add Page Numbers with consecutive numbering across all documents
3. Use Add Stamp to add exhibit numbers or confidentiality notices
4. Convert to PDF/A for long-term archival as required by many courts
5. Optionally Certificate Sign each document for digital authenticity

12.7 Extract Specific Content from a Large Document

Goal: Pull specific pages, images, or data from a large PDF.

12.8 Batch Processing via API

Goal: Process hundreds of PDFs programmatically using the REST API.

import requests
from pathlib import Path

API_BASE = "http://localhost:8080/api/v1"

def compress_pdf(input_path, output_path, level=3):
    """Compress a single PDF file."""
    with open(input_path, "rb") as f:
        response = requests.post(
            f"{API_BASE}/general/compress-pdf",
            files={"fileInput": f},
            data={"optimizeLevel": level}
        )
    response.raise_for_status()
    with open(output_path, "wb") as f:
        f.write(response.content)

def ocr_pdf(input_path, output_path, languages="eng"):
    """Apply OCR to a scanned PDF."""
    with open(input_path, "rb") as f:
        response = requests.post(
            f"{API_BASE}/misc/ocr-pdf",
            files={"fileInput": f},
            data={"languages": languages, "ocrType": "skip-text"}
        )
    response.raise_for_status()
    with open(output_path, "wb") as f:
        f.write(response.content)

# Compress all PDFs in a directory
input_dir = Path("./input")
output_dir = Path("./output")
output_dir.mkdir(exist_ok=True)

for pdf in input_dir.glob("*.pdf"):
    compress_pdf(pdf, output_dir / pdf.name)
    print(f"Compressed: {pdf.name}")

12.9 Create a Dark Mode PDF

Goal: Convert a white-background PDF to a dark-background version for comfortable nighttime reading.

1. Upload to Replace/Invert Colors
2. Select full color inversion
3. Download the dark-mode version

White text on a dark background is easier on the eyes for extended screen reading sessions.

12.10 Add a Letterhead to Every Page

Goal: Apply a company letterhead template to an existing document.

1. Create a PDF with just the letterhead design (logo, borders, header text) on a single page
2. Upload the document as the base PDF in Overlay PDF
3. Upload the letterhead PDF as the overlay
4. Select "Underlay" mode (so the letterhead appears behind the document content)
5. Select "Repeat" mode (so the single letterhead page applies to every document page)
6. Click Submit

12.11 Convert Scanned Multi-Photo Pages

Goal: You scanned a batch of physical photos on a flatbed scanner, with multiple photos per scan. Separate them into individual images.

1. Upload the scan PDF to Extract Image Scans
2. The tool detects individual photo boundaries on each page
3. Download the separated, cropped images

13. How It Works

13.1 Architecture Overview

Stirling-PDF uses a layered architecture:

• Frontend: React application built with TypeScript and the Mantine UI framework. In Docker, it is served by the container's web server. In the desktop app, it renders inside a Tauri webview.
• Backend: Spring Boot 4.0.5 application running on Java 21 that exposes the REST API at /api/v1/ and handles all PDF processing.
• Processing engines: Apache PDFBox for core PDF manipulation, LibreOffice for office document conversion, Tesseract for OCR, Ghostscript and qpdf for specialized tasks, and various other libraries for specific operations.

13.2 Processing Flow

When you submit a PDF operation:

1. The frontend uploads the file(s) to the backend via multipart REST API call
2. The backend validates the request, checks file size limits, and verifies the operation is enabled
3. The appropriate processor handles the operation using in-memory buffers or temporary files
4. The result is streamed back as a file download response
5. No files are stored permanently on the server -- temporary files are cleaned up after the response

13.3 Privacy Model

All processing happens locally within your Docker container or desktop application:

• No files are transmitted to external servers under any circumstances
• No telemetry, analytics, or usage data is collected or phoned home
• When METRICS_ENABLED is true, it only enables local Prometheus-compatible metrics endpoints -- no data is sent externally
• No internet connection is required after initial installation (except for downloading OCR language packs via TESSERACT_LANGS)

13.4 Supported PDF Standards

Stirling-PDF processes:

• PDF versions 1.0 through 2.0
• PDF/A variants (1b, 2b, 3b) for archival compliance
• Encrypted PDFs (when the correct password is supplied)
• Tagged PDFs with accessibility structures
• PDFs containing embedded fonts, images, forms, annotations, JavaScript, and attachments

14. Troubleshooting

Warning

When troubleshooting any issue, always check container logs first: docker logs stirling-pdf --tail 200. The Java stack traces contain the specific error cause, which is often more informative than the message shown in the browser UI.

Error: Container crashes immediately after starting

Cause: Insufficient memory allocated to Docker. The :fat image requires at least 6 GB.

Solution:

1. Check Docker resource limits: Docker Desktop, then Settings, then Resources, then Memory
2. Increase memory to at least 6 GB for :fat, 4 GB for :latest, 2 GB for :ultra-lite
3. Restart Docker Desktop after changing memory allocation
4. Restart the container: docker compose up -d

Prevention: Always set explicit memory limits in your docker-compose.yml under deploy.resources.limits.memory.

Error: LibreOffice conversion fails or "File to PDF" tool is grayed out

Cause: LibreOffice is not installed in the container. The :ultra-lite image does not include LibreOffice, and :latest may require manual installation.

Solution:

• Switch to the :fat image, which bundles LibreOffice and all dependencies
• Or install LibreOffice manually in a custom Dockerfile extending :latest

Prevention: Use the :fat image from the start if you need any office document conversions (DOCX, XLSX, PPTX to PDF).

Error: OCR produces empty or garbled text

Cause: Wrong language selected for the document, or the required language data files are missing.

Solution:

1. Verify the correct language is selected for your document
2. List available language data files:

   docker exec stirling-pdf ls /usr/share/tessdata/
   

3. Add missing languages via the TESSERACT_LANGS environment variable:

   environment:
     TESSERACT_LANGS: "deu,fra,jpn"
   

4. Or manually download .traineddata files into the tessdata volume

Prevention: Pre-configure TESSERACT_LANGS in your compose file for all languages you regularly encounter.

Error: Upload fails with "File too large"

Cause: The file exceeds the configured maximum upload size (default 100 MB).

Solution:

1. Increase SYSTEM_MAXFILESIZE:

   environment:
     SYSTEM_MAXFILESIZE: "500"
   

2. If behind a reverse proxy, also increase the proxy's upload limit:
   • Nginx: client_max_body_size 500M;
   • Traefik: configure buffering middleware
   • Apache: LimitRequestBody 524288000
3. Restart the container after changing the variable

Prevention: Set SYSTEM_MAXFILESIZE appropriately for your largest expected files during initial setup.

Error: "Permission denied" writing to mounted volumes

Cause: The container process runs as a different user than the host directory owner.

Solution:

1. Set PUID and PGID to match your host user's UID and GID:

   environment:
     PUID: "1000"
     PGID: "1000"
   

2. Or fix host directory permissions:

   sudo chown -R 1000:1000 ./stirling/
   

Prevention: Always configure PUID and PGID in your compose file before first launch.

Error: Health check failing or container shows "unhealthy"

Cause: The application has not finished starting up, or it encountered an error during initialization.

Solution:

1. Check container logs for startup errors:

   docker logs stirling-pdf --tail 100
   

2. If the application is still starting, increase start_period:

   healthcheck:
     start_period: 120s
   

3. Verify port 8080 is not already in use on the host:

   ss -tlnp | grep 8080
   

Prevention: Set start_period to at least 60s on slower hardware or virtualized environments.

Error: "Constraint already exists" during database import

Cause: Known issue (#4405) where importing a database backup encounters duplicate constraint definitions from schema evolution.

Solution:

1. Export the database from a clean, running instance of the same version
2. For cross-version migrations, perform a fresh install and re-configure rather than importing old backups

Prevention: Only import databases exported from the same Stirling-PDF version.

Error: Split PDF into Sections removes input fields

Cause: Known issue (#1612). The section-splitting process renders pages as images, which does not preserve interactive form fields.

Solution:

• Flatten the PDF first if you need to preserve the visual appearance of filled form fields (the fields become static content)
• Or use Extract Pages instead if you only need specific pages with form fields intact

Prevention: Avoid section-splitting on PDFs that contain interactive form fields.

Error: Windows SmartScreen blocks the desktop installer

Cause: Known false positive (#6120, #5600). Windows SmartScreen flags the installer because it has not yet built sufficient download reputation with Microsoft's threat intelligence systems.

Solution:

1. On the SmartScreen warning dialog, click More info
2. Click Run anyway
3. The application is safe -- this is a code-signing reputation issue, not malware

Prevention: This resolves automatically as more users install the application and SmartScreen's reputation database updates.

Error: PDF conversion produces blank pages

Cause: The PDF uses fonts that are not available in the container, or contains complex vector graphics that fail to render during conversion.

Solution:

1. Install additional fonts:

   docker exec stirling-pdf apt-get update && \
     apt-get install -y fonts-liberation fonts-noto fonts-noto-cjk
   

2. Try a different conversion path (e.g., PDF to Image at high DPI, then Image to PDF)

Prevention: Use the :fat image, which includes a broader font selection.

Error: OutOfMemoryError in Java logs

Cause: The PDF being processed requires more heap memory than the JVM is configured to use. Very large PDFs (1000+ pages, many high-resolution images) are the typical trigger.

Solution:

1. Increase JVM heap memory:

   environment:
     JAVA_CUSTOM_OPTS: "-Xmx4g"
   

2. Increase the Docker container memory limit proportionally (JVM heap + overhead):

   deploy:
     resources:
       limits:
         memory: 6G
   

3. For extremely large PDFs, split them into smaller chunks before processing

Prevention: Set JAVA_CUSTOM_OPTS with appropriate -Xmx values during initial deployment.

Error: Slow startup time (more than 2 minutes)

Cause: Initialization tasks (loading fonts, warming up LibreOffice, checking dependencies, downloading OCR language packs) take time, especially on first launch or slower hardware.

Solution:

1. This is expected behavior on first start or after updates
2. Increase the health check start_period to avoid premature "unhealthy" status:

   healthcheck:
     start_period: 120s
   

3. Use the performance JVM profile on capable hardware:

   environment:
     STIRLING_JVM_PROFILE: "performance"
   

Error: Cannot access the UI from another machine on the network

Cause: The container port mapping may be binding to localhost only, or a host firewall is blocking the port.

Solution:

1. Ensure the port mapping binds to all interfaces:

   ports:
     - "0.0.0.0:8080:8080"
   

2. Check and open the host firewall:

   sudo ufw allow 8080/tcp
   

3. Verify the container is running and healthy:

   docker ps | grep stirling
   

Error: Watermark not appearing on all pages

Cause: The watermark configuration targets specific pages instead of the entire document.

Solution: In the watermark tool, select "All pages" instead of specifying a page range. Alternatively, use the page selection 1-9999 to cover all pages.

Error: Merge produces corrupted output

Cause: One or more input PDFs are malformed or use incompatible PDF features that conflict during merge.

Solution:

1. Run each input PDF through Repair first
2. Try merging a subset to identify the problematic file
3. Convert the problematic PDF to PDF/A first (which normalizes the structure), then merge

Error: Certificate signing fails with "keystore" error

Cause: The certificate file is not in the expected .p12/.pfx format, or the certificate password is incorrect.

Solution:

1. Verify the certificate is in PKCS#12 format (.p12 or .pfx)
2. Double-check the password (certificate passwords are case-sensitive)
3. If your certificate is in PEM format, convert it:

   openssl pkcs12 -export -in cert.pem -inkey key.pem -out certificate.p12
   

Error: PDF/A conversion fails

Cause: The source PDF contains elements incompatible with the PDF/A standard -- embedded multimedia, JavaScript, external font references, or non-embeddable fonts.

Solution:

1. Run Sanitize PDF first to remove JavaScript and multimedia
2. Run Flatten to resolve annotation and form issues
3. Retry the PDF/A conversion
4. If it still fails, the PDF likely has non-embeddable fonts -- try converting to images first, then back to PDF/A

Error: Docker image pull fails with "manifest unknown"

Cause: The specified image tag does not exist on the registry, or there is a temporary registry issue.

Solution:

1. Verify the correct tag (:latest, :fat, or :ultra-lite):

   docker pull docker.stirlingpdf.com/stirlingtools/stirling-pdf:fat
   

2. Try Docker Hub as an alternative registry:

   docker pull stirlingtools/stirling-pdf:fat
   

Error: Pipeline fails partway through

Cause: An operation in the pipeline produces output that is incompatible with the next operation's expected input.

Solution:

1. Run each pipeline step manually in sequence to identify which transition fails
2. Verify that each step's output format is accepted by the next step
3. Insert intermediate steps if needed (e.g., Flatten between form-related operations and image-related operations)

Error: OCR is extremely slow (taking many minutes per page)

Cause: OCR is inherently CPU-intensive. Large pages, high resolution, or complex layouts increase processing time.

Solution:

1. Use "Skip text" mode to only OCR pages that lack existing text
2. Split large documents and process chunks separately
3. Allocate more CPU cores to the container:

   deploy:
     resources:
       limits:
         cpus: "4"
   

4. Reduce input image resolution if acceptable for your use case

Error: Fonts display incorrectly after conversion

Cause: The PDF references fonts that are not embedded in the file and are not available in the container's font library.

Solution:

1. Install the required fonts inside the container:

   docker exec -it stirling-pdf bash
   apt-get update && apt-get install -y fonts-liberation2 fonts-noto-cjk
   

2. For persistent font installations, mount a host fonts directory or extend the Dockerfile
3. Restart the container after installing fonts

Error: API returns 413 (Request Entity Too Large)

Cause: The reverse proxy in front of Stirling-PDF has a lower upload size limit than the application itself.

Solution:

• Nginx: client_max_body_size 500M; in the location or server block
• Traefik: Configure buffering middleware with appropriate maxRequestBodyBytes
• Apache: LimitRequestBody 524288000 in the virtual host or directory configuration
• Caddy: request_body { max_size 500MB } in the site block

Error: "The document has no pages" after split or extract

Cause: The page selection expression evaluated to an empty set -- no pages matched the criteria.

Solution:

1. Check the total page count with Get PDF Info
2. Review the page selection expression for off-by-one errors or out-of-range page numbers
3. Test with a simple range first (e.g., 1-5) before using complex expressions

Error: Annotations lost after merge

Cause: Certain merge modes do not transfer interactive annotation data from all input documents.

Solution:

1. If annotations must remain visible, Flatten each input PDF before merging (annotations become permanent page content)
2. If annotations must stay interactive, try merging fewer files at a time

Error: Cannot save settings -- "Read-only file system"

Cause: The /configs volume is not mounted, is mounted read-only, or the container user lacks write permission.

Solution:

1. Ensure the volume is mounted with rw access:

   volumes:
     - ./stirling/config:/configs:rw
   

2. Verify host directory permissions and ownership:

   ls -la ./stirling/config/
   sudo chown -R 1000:1000 ./stirling/config/
   

Caution

Auto-redact uses pattern matching and may miss sensitive data in unusual formats (international phone numbers, non-standard identifiers, handwritten text in scanned documents). Never rely solely on auto-redact for compliance-critical redactions. Always follow up with a manual review of the output document.

Error: Auto-redact misses some sensitive data

Cause: Auto-redact relies on regular expression pattern matching. Unusual formats (international phone numbers, custom identifiers, abbreviations) may not match the built-in patterns.

Solution:

1. Run auto-redact first to catch standard patterns
2. Follow up with manual Redact to handle anything that was missed
3. Use custom regex patterns if the tool supports them for your specific data format
4. Always verify by searching the output PDF for the sensitive terms

Prevention: Build a pipeline that runs auto-redact followed by manual review for any compliance-critical use case.

Error: PDF comparison shows no differences when differences exist

Cause: The comparison operates on text content. If differences are purely visual (font rendering, image quality, spacing) they may not be detected as text-level changes.

Solution: For visual comparison, convert both PDFs to images at the same DPI using PDF to Image, then use an external image comparison tool.

Error: Booklet imposition produces incorrect page order

Cause: The source PDF page count is not a multiple of 4. Booklet printing requires page counts divisible by 4.

Solution: Add blank pages to make the total count a multiple of 4 before running booklet imposition. For example, for a 14-page document, add 2 blank pages to reach 16.

Error: Downloaded file is 0 bytes or empty

Cause: The processing operation failed silently, or a browser extension intercepted the download.

Solution:

1. Check the container logs for errors during the failed operation
2. Try in a private/incognito browser window (disables extensions)
3. Try a different browser
4. Use the API directly with curl to bypass browser-related issues

Error: Application language does not change after setting locale

Cause: The locale change may require a container restart, or the specified locale is not supported.

Solution:

1. Set SYSTEM_DEFAULTLOCALE to a supported locale code (e.g., en-US, de-DE, fr-FR, ja-JP)
2. Restart the container:

   docker compose restart stirling-pdf
   

3. Clear browser cache and cookies for the application

15. Frequently Asked Questions

Q: Is Stirling-PDF really free? Stirling-PDF is open source. The self-hosted version includes all core features at no cost. Some advanced features in the SaaS/proprietary edition may have different licensing.

Q: Does Stirling-PDF send my files to any server? No. All processing occurs locally within your Docker container or desktop application. No files, metadata, or telemetry are transmitted to external servers. This is a core design principle of the project.

Q: What is the maximum file size I can process? The default limit is 100 MB, controlled by SYSTEM_MAXFILESIZE. You can increase this to any value your hardware supports. Very large files require proportional memory allocation.

Q: Which Docker image should I use?

• :fat if you need all features (office conversion, OCR, all fonts) and have 6+ GB memory
• :latest if you manage LibreOffice and Tesseract installations yourself
• :ultra-lite if you only need basic PDF operations and want the smallest, fastest image

Q: How do I update to a new version? Pull the latest image and restart:

docker compose pull
docker compose up -d

Data persists in mounted volumes. No configuration or data is lost during updates.

Q: Can I run multiple instances behind a load balancer? Yes. Processing is stateless -- each request is self-contained. Run multiple MODE=BOTH containers behind any load balancer, or use MODE=FRONTEND with multiple MODE=BACKEND instances for horizontal scaling.

Q: How do I add OCR support for my language? Set TESSERACT_LANGS with comma-separated Tesseract language codes:

environment:
  TESSERACT_LANGS: "deu,fra,spa,jpn,chi_sim,kor,ara"

The container downloads the language data automatically on startup.

Q: Can I use Stirling-PDF without Docker? Yes. Build from source with Java 21 and Gradle, or install the desktop application (available for Windows, macOS, and Linux). The desktop app packages everything needed to run locally.

Q: Does Stirling-PDF support batch processing? Yes, through multiple methods:

1. Multi-file upload in the web UI for supported tools
2. The REST API for scripted automation (any programming language that can make HTTP requests)
3. Pipelines for chaining multiple operations
4. Watched folder automation for file-drop processing

Q: How do I enable HTTPS? Stirling-PDF serves HTTP on port 8080. Place a reverse proxy (Traefik, Nginx, Caddy) in front of it to terminate TLS/SSL. See Section 11.4 for proxy configuration examples and the Admin Guide for complete deployment configurations.

Q: What happens if the container crashes during processing? No files are permanently stored on the server. Re-upload the file and try again after restarting the container. Your original file is never modified by any Stirling-PDF operation.

Q: Can I customize the UI appearance? Yes. Mount the /customFiles volume and add custom CSS, logos, and branding. Use environment variables UI_APPNAME, UI_HOMEDESCRIPTION, and UI_APPNAMENAVBAR for text customization.

Q: Which browsers are supported? All modern browsers: Chrome, Firefox, Safari, Edge, and their derivatives. Internet Explorer is not supported.

Q: Is there an API rate limit? The self-hosted version has no built-in rate limiting. For production deployments serving many users, configure rate limiting in your reverse proxy.

Q: How do I secure my instance for multi-user access?

1. Set DOCKER_ENABLE_SECURITY=true and SECURITY_ENABLELOGIN=true
2. Configure initial admin credentials in settings.yml
3. Set SECURITY_CUSTOMGLOBALAPIKEY if API access needs authentication
4. Place behind a reverse proxy with HTTPS
5. See the Admin Guide for full security hardening.

Q: What PDF versions does Stirling-PDF support? PDF 1.0 through 2.0, including all PDF/A archival variants. Encrypted PDFs are supported when the correct password is provided.

Q: Can I process password-protected PDFs? Yes. Tools that operate on encrypted PDFs prompt for the password. Use Remove Password to permanently decrypt a file (requires the current password).

Q: Does the desktop app have the same features as Docker? The desktop app includes all core features. Features dependent on LibreOffice or Tesseract require those tools to be available on your system. Some desktop builds bundle these dependencies, while others require separate installation.

Q: How do I report a bug or request a feature? Open an issue on the GitHub repository. Include the Stirling-PDF version, Docker image variant, browser and OS information, and detailed steps to reproduce.

Q: What is the difference between "Add Watermark" and "Add Stamp"? A watermark is typically semi-transparent text or an image placed as a background mark (behind or over content, usually at reduced opacity). A stamp is an opaque, clearly visible label placed on top of page content, such as "CONFIDENTIAL", "APPROVED", or "DRAFT".

Q: Can I run Stirling-PDF on a Raspberry Pi or other ARM device? Yes, with limitations. Use the :ultra-lite image for the smallest resource footprint. ARM images are available. Expect slower performance on ARM devices, especially for OCR and office document conversions. The :fat image may exceed the memory available on most Raspberry Pi models.

Q: How do I handle non-Latin scripts (Arabic, Chinese, Japanese, Korean, Hindi)?

1. Install OCR language data for the relevant languages (see Section 7.1)
2. Install CJK and multilingual fonts inside the container:

   apt-get install -y fonts-noto-cjk fonts-noto-color-emoji fonts-noto
   

3. Set SYSTEM_DEFAULTLOCALE to match your primary audience

Q: What is the Pipeline feature? Pipelines chain multiple PDF operations into a single automated workflow. Define a sequence like OCR, then compress, then watermark, then encrypt -- and run it with one click or one API call instead of four separate steps.

Q: Can Stirling-PDF handle scanned images that are not yet PDFs? Yes. Use Image to PDF to convert scanned images (JPEG, PNG, TIFF) to PDF format. Then apply OCR PDF to make the text searchable. Extract Image Scans can also split a flatbed scan of multiple photos into individual cropped images.

Q: How do I integrate Stirling-PDF into my existing application or workflow? Use the REST API. Every operation available in the web UI has a corresponding API endpoint. The Swagger documentation at /swagger-ui/index.html provides the complete API reference with request parameters, response formats, and interactive testing.

Q: Does Stirling-PDF modify my original file? Never. Every operation produces a new output file. The uploaded original is processed in memory, used as input, and discarded after the result is generated. Your source file is never written to or altered.

Q: What exactly does "sanitize" do? Sanitization removes potentially dangerous or privacy-leaking content: embedded JavaScript (malware risk), file attachments (malware delivery), metadata (author name, GPS coordinates, creation software, edit history), and automatic actions (URLs that open on document load, print triggers).

Q: Can I use Stirling-PDF with a CI/CD pipeline? Yes. Run Stirling-PDF as a service in your CI environment and call its API endpoints from your pipeline scripts. For example, in a GitHub Actions workflow, start the container in the background, wait for the health check, then use curl to process documents.

Q: What is the difference between "Extract Pages" and "Split Pages"? Extract Pages produces a single PDF containing only the pages you specify. Split Pages divides a PDF into multiple separate files at the page numbers you specify. For example, with a 20-page PDF: "Extract 5-10" gives you one 6-page PDF. "Split at 5, 10" gives you three PDFs (pages 1-4, 5-9, 10-20).

Q: How do I process a large number of files efficiently?

1. Use the API for parallel processing from a script
2. Create a pipeline for multi-step workflows and submit files via the pipeline API
3. Use watched folders for continuous automated processing
4. If running via API, you can make concurrent requests -- each is processed independently

Q: Is the "Scanner Effect" tool the opposite of OCR? Not exactly. OCR converts images of text into machine-readable text. Scanner Effect makes a digital PDF look like it was scanned (adding visual noise, slight rotation, and other artifacts) but does not remove the underlying text. The text remains searchable after applying the scanner effect.