Stirling

Unix Installation

Stirling PDF on Linux is available as a native desktop application or as a server using the JAR file.

Native Linux desktop app with all PDF tools available.

What You Get#

  • ✅ Native Linux application - Integrated with your desktop environment
  • ✅ Open PDFs directly - Double-click any PDF to open in Stirling-PDF
  • ✅ No login required - Install and start using PDF tools right away
  • ✅ Processes files locally - All your PDF processing stays on your device
  • ✅ Optional server connection - Connect to Stirling Cloud or your own self-hosted server for advanced tools like OCR and document conversions
  • ✅ All local tools included - Merge, split, rotate, sign, and more work without any server
  • ✅ Better performance - Native Linux integration
  • ✅ No browser needed - Standalone application

Installation#

Pick whichever package format matches your distribution.

bash
wget https://files.stirlingpdf.com/linux-installer.deb
sudo dpkg -i linux-installer.deb

Launch via your application menu or stirling-pdf from the terminal.

bash
wget https://files.stirlingpdf.com/linux-installer.rpm
sudo dnf install ./linux-installer.rpm

No install required - download, mark executable, run:

bash
wget https://files.stirlingpdf.com/linux-installer.AppImage
chmod +x linux-installer.AppImage
./linux-installer.AppImage

If you see fuse: device not found on Ubuntu 22.04+, install FUSE:

bash
sudo apt-get install libfuse2

Install via any AUR helper:

bash
paru -S stirling-pdf-desktop
# or: yay -S stirling-pdf-desktop

Package: stirling-pdf-desktop.

Connecting to a server#

The desktop app works fully offline for local PDF tools like merging, splitting, rotating, and signing. If you need advanced server-side features like OCR or document format conversions, you can connect to a server at any time. See Modes for how each mode is licensed.

Stirling Cloud

  • Sign in with your Stirling Cloud account
  • Gives access to advanced tools powered by server-side processing
  • See Modes for what this mode includes

Self-hosted Server

  • Enter the URL of your own Stirling-PDF server instance (e.g., http://192.168.1.53:8080)
  • Full control over your data and processing
  • Useful for team deployments or when you want all features on your own infrastructure

Managed deployment (MDM)#

To pre-configure and lock the app across managed Linux desktops - server URL, connection lock, and update behaviour - see Managed Desktop Deployment.

Server Version (For Hosting and Sharing)#

To run the application without Docker/Podman, you will need to manually install all dependencies and build the necessary components.

Note that some dependencies might not be available in the standard repositories of all Linux distributions, and may require additional steps to install.

The following guide assumes you have a basic understanding of using a command line interface in your operating system.

It should work on most Linux distributions and MacOS. For Windows, you might need to use Windows Subsystem for Linux (WSL) for certain steps. The amount of dependencies is to actually reduce overall size, ie installing LibreOffice sub components rather than full LibreOffice package.

You could theoretically use a Distrobox/Toolbox, if your Distribution has old or not all Packages. But you might just as well use the Docker Container then.

Step 1: Prerequisites#

Install the following software, if not already installed:

  • Java 25 or later
  • Gradle 7.0 or later (included within repo so not needed on server)
  • Git
  • Python 3.8 (with pip)
  • Make
  • GCC/G++
  • Automake
  • Autoconf
  • libtool
  • pkg-config
  • zlib1g-dev
  • libleptonica-dev
bash
sudo apt-get update
sudo apt-get install -y git automake autoconf libtool \
    libleptonica-dev pkg-config zlib1g-dev make g++ \
    openjdk-25-jdk python3 python3-pip
bash
sudo dnf install -y git automake autoconf libtool \
    leptonica-devel pkg-config zlib-devel make gcc-c++ \
    java-25-openjdk python3 python3-pip
bash
nix-channel --update
nix-env -iA nixpkgs.jdk25 nixpkgs.git nixpkgs.python38 \
    nixpkgs.gnumake nixpkgs.libgcc nixpkgs.automake \
    nixpkgs.autoconf nixpkgs.libtool nixpkgs.pkg-config \
    nixpkgs.zlib nixpkgs.leptonica

Step 2: Clone and Build jbig2enc (Only required for certain OCR functionality)#

bash
mkdir ~/.git
cd ~/.git &&\
git clone https://github.com/agl/jbig2enc.git &&\
cd jbig2enc &&\
./autogen.sh &&\
./configure &&\
make &&\
sudo make install
bash
mkdir ~/.git
cd ~/.git &&\
git clone https://github.com/agl/jbig2enc.git &&\
cd jbig2enc &&\
./autogen.sh &&\
./configure &&\
make &&\
sudo make install
bash
nix-env -iA nixpkgs.jbig2enc

Step 3: Install Additional Software#

Next we need to install LibreOffice for conversions, tesseract for OCR, and opencv for pattern recognition functionality.

Install the following software:

  • libreoffice (libreoffice-core libreoffice-common libreoffice-writer libreoffice-calc libreoffice-impress)
  • python3-uno
  • unoserver
  • pngquant
  • tesseract
  • opencv-python-headless
bash
sudo apt-get install -y libreoffice-writer libreoffice-calc libreoffice-impress tesseract-ocr
pip3 install uno opencv-python-headless unoserver pngquant WeasyPrint --break-system-packages
bash
sudo dnf install -y libreoffice-writer libreoffice-calc libreoffice-impress tesseract
pip3 install uno opencv-python-headless unoserver pngquant WeasyPrint
bash
nix-env -iA nixpkgs.libreoffice nixpkgs.tesseract nixpkgs.poppler_utils
pip3 install uno opencv-python-headless unoserver pngquant WeasyPrint

Step 4: Grab latest Stirling PDF Jar#

Stirling PDF comes in three different JAR files:

Stirling-PDF-with-login.jar (Recommended - Full Features):

  • Download: Stirling-PDF-with-login.jar
  • Bundles frontend UI + backend server in one file
  • Includes authentication and additional features - requires user login (default credentials: admin / stirling)
  • Recommended for all users - personal, shared, or enterprise deployments

Stirling-PDF.jar (Plain JAR - Basic Features):

  • Download: Stirling-PDF.jar
  • Bundles frontend UI + backend server in one file
  • Basic version - no authentication, core features only
  • Only use if you require no login at all and don't mind missing certain features

Stirling-PDF-server.jar (Backend Only - Advanced):

  • Download: Stirling-PDF-server.jar
  • Backend server only (no bundled UI)
  • No authentication - API access only
  • For desktop app backend, custom frontend, or API integrations

Example download and setup:

bash
sudo wget https://files.stirlingpdf.com/Stirling-PDF.jar
sudo chmod +x Stirling-PDF.jar

Step 4b: Clone the Stirling-PDF Repository#

You need the repository to get the scripts folder, which contains Python scripts used by OpenCV for certain PDF operations.

bash
git clone https://github.com/Stirling-Tools/Stirling-PDF.git

Step 5: Move JAR and Scripts to Desired Location#

Move the downloaded JAR file and the scripts folder from the cloned repository to a desired location, for example, /opt/Stirling-PDF/. The scripts folder is required for the Python scripts using OpenCV.

bash
sudo mkdir -p /opt/Stirling-PDF &&\
sudo mv Stirling-PDF.jar /opt/Stirling-PDF/ &&\
sudo cp -r Stirling-PDF/scripts /opt/Stirling-PDF/ &&\
echo "JAR and scripts installed."
bash
sudo mkdir -p /opt/Stirling-PDF &&\
sudo mv Stirling-PDF.jar /opt/Stirling-PDF/ &&\
sudo cp -r Stirling-PDF/scripts /opt/Stirling-PDF/ &&\
echo "JAR and scripts installed."
bash
mkdir -p ~/Stirling-PDF &&\
mv Stirling-PDF.jar ~/Stirling-PDF/ &&\
cp -r Stirling-PDF/scripts ~/Stirling-PDF/

Step 6: OCR Language Support#

If you plan to use the OCR (Optical Character Recognition) functionality, you might need to install language packs for Tesseract if running non-english scanning.

bash
sudo apt update &&\
# All languages
# sudo apt install -y 'tesseract-ocr-*'

# Find languages:
apt search tesseract-ocr-

# View installed languages:
dpkg-query -W tesseract-ocr- | sed 's/tesseract-ocr-//g'
bash
# All languages
# sudo dnf install -y tesseract-langpack-*

# Find languages:
dnf search -C tesseract-langpack-

# View installed languages:
rpm -qa | grep tesseract-langpack | sed 's/tesseract-langpack-//g'
bash
nix-env -iA nixpkgs.tesseract

Note: Nix Package Manager pre-installs almost all the language packs when tesseract is installed.

  1. Download the desired language pack(s) by selecting the .traineddata file(s) for the language(s) you need.
  2. Place the .traineddata files in the Tesseract tessdata directory: /usr/share/tessdata
  3. Please view tesseract install guide for more info.

IMPORTANT: DO NOT REMOVE EXISTING eng.traineddata, IT'S REQUIRED.

Step 7: Run Stirling PDF#

bash
java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar
bash
java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar
bash
java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar

Since libreoffice, soffice, and conversion tools have their dbus_tmp_dir set as dbus_tmp_dir="/run/user/$(id -u)/libreoffice-dbus", you get the following error: [Thread-7] INFO s.s.SPDF.utils.ProcessExecutor - mkdir: cannot create directory '/run/user/1501': Permission denied To resolve this, use: bash mkdir temp export DBUS_SESSION_BUS_ADDRESS="unix:path=./temp"

Step 8: Adding a Desktop Icon#

This will add a modified Appstarter to your Appmenu.

bash
location=$(pwd)/gradlew
image=$(pwd)/docs/stirling.svg

cat > ~/.local/share/applications/Stirling-PDF.desktop <<EOF
[Desktop Entry]
Name=Stirling PDF;
GenericName=Launch StirlingPDF and open its WebGUI;
Category=Office;
Exec=xdg-open http://localhost:8080 && nohup $location java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar &;
Icon=$image;
Keywords=pdf;
Type=Application;
NoDisplay=false;
Terminal=true;
EOF

Note: Currently the app will run in the background until manually closed.

Optional: Changing the Host and Port#

To override the default configuration, you can add the following to the configs/custom_settings.yml file inside your install directory (for example, /opt/Stirling-PDF/configs/custom_settings.yml):

yaml
server:
  host: 0.0.0.0
  port: 3000

For systemd add in the .env file (see run as service for setting environment variables):

bash
SERVER_HOST="0.0.0.0"
SERVER_PORT="3000"

Note: The file custom_settings.yml is created after the first application launch. To have it before that, you can create the directory and add the file yourself.

Optional: Run Stirling PDF as a service (requires root).#

First create a .env file, where you can store environment variables:

touch /opt/Stirling-PDF/.env

In this file you can add all variables, one variable per line, as stated in the main readme (for example SYSTEM_DEFAULTLOCALE="de-DE").

Create a new file where we store our service settings and open it with nano editor:

nano /etc/systemd/system/stirlingpdf.service

Paste this content, make sure to update the filename of the jar-file. Press Ctrl+S and Ctrl+X to save and exit the nano editor:

[Unit]
Description=Stirling-PDF service
After=syslog.target network.target

[Service]
SuccessExitStatus=143

User=root
Group=root

Type=simple

EnvironmentFile=/opt/Stirling-PDF/.env
WorkingDirectory=/opt/Stirling-PDF
ExecStart=/usr/bin/java -jar Stirling-PDF-*.jar
ExecStop=/bin/kill -15 $MAINPID

[Install]
WantedBy=multi-user.target

Notify systemd that it has to rebuild its internal service database (you have to run this command every time you make a change in the service file):

sudo systemctl daemon-reload

Enable the service to tell the service to start it automatically:

sudo systemctl enable stirlingpdf.service

See the status of the service:

sudo systemctl status stirlingpdf.service

Manually start/stop/restart the service:

sudo systemctl start stirlingpdf.service
sudo systemctl stop stirlingpdf.service
sudo systemctl restart stirlingpdf.service

Starting unoserver alongside Stirling PDF#

To ensure that unoserver is running alongside Stirling PDF, you need to start it with the following command:

bash
unoserver --port 2003 --interface 0.0.0.0

You can add this command to your startup script or systemd service file to ensure it starts automatically with Stirling PDF.

Customizing Paths in settings.yml#

If the install path is different, it can be customized in settings.yml:

yaml
system:
  customPaths:
    pipeline:
      watchedFoldersDir: "" #Defaults to /pipeline/watchedFolders
      finishedFoldersDir: "" #Defaults to /pipeline/finishedFolders
    operations:
      weasyprint: "" #Defaults to /opt/venv/bin/weasyprint
      unoconvert: "" #Defaults to /opt/venv/bin/unoconvert
Edit this page on GitHub