Stirling PDF Open Source: A Complete Guide
Learn how to deploy Stirling PDF self-hosted for free. 50+ PDF tools, zero cloud dependency, full privacy control. Docker quick start and production setup.
- Stirling PDF is a free, open-source toolkit with 50+ PDF operations (merge, split, OCR, sign, redact) and 96.9K GitHub stars
- The MIT-licensed core runs entirely on your server or laptop with zero cloud dependency; files never leave your infrastructure
- Deploy in Docker with one command or scale with Kubernetes; no installation required, no licensing costs
- Privacy and audit control are built-in because you own the server; perfect for compliance-sensitive documents
- As your team and file volume grow, managed hosting removes the operational burden while keeping full control
Stirling PDF is a free, open-source PDF toolkit with 96.9K GitHub stars and 30M+ downloads. It runs locally on your machine, in a Docker container, or on a Kubernetes cluster, keeping your files off cloud servers entirely. If you process PDFs regularly and want offline capability or compliance control, Stirling PDF is worth running yourself.
What Is Stirling PDF?
Stirling PDF started as a personal project and has grown to serve 55,000 companies globally. It is a web-based PDF application packaged for self-hosted deployment. The core code is MIT-licensed, with proprietary modules locked behind paid Server and Enterprise tiers. You get access to 50+ PDF operations: merge, split, rotate, crop, compress, convert, OCR, watermark, sign, and redact files.
The appeal is simple. Cloud PDF tools (Smallpdf, iLovePDF, Adobe) are convenient but add a data residency risk. You upload files to foreign servers, trust their encryption, and pay per month or per operation. Stirling PDF flips that: you deploy it, your files stay on your hardware, and there is no recurring cost. The free tier is not a trial. It is designed to be your permanent tool. Individual users, small teams, and enterprises all run it without paying anything, ever.
Stirling PDF is not a consumer product like Preview (Mac) or Adobe Reader. It is a backend service you access through a web browser. When you deploy it, you get a URL (localhost port 8080 on your laptop, or your company domain on a server). You load that URL, upload a PDF, pick an operation, download the result. No accounts, no limits on file size or operation count, no surprise charges.
Free vs. Paid: What is Included?
This is where the open-core model becomes clear. The free tier includes all 50+ PDF tools: everything from basic merge-and-split to OCR and document signing. If you self-host from the GitHub repo (MIT license), you pay nothing. The free Editor is permanent. No expiration, no nagware, no feature lockout.
Paid tiers (Server and Enterprise) unlock proprietary modules in directories marked off-limits in the free MIT code. These include admin dashboards, user management, audit logging, and API rate-limit controls. If you are running a small single-user instance or a team Docker setup on your own server, free is enough. If you are a 100-person company and need centralized administration, activity logs, or SSO integration, you will want the paid license.
Stirling charges for support and hosted SaaS options too, but the core toolkit remains free and open. This is not a trick. The licensing is explicit in the GitHub repo: free MIT code covers the core PDF operations, proprietary modules are separated into their own directories, and you are told upfront which is which.
Deployment Options: Desktop, Browser, or Self-Hosted?
You have three paths into Stirling PDF. First, the desktop app: Windows, macOS, or Linux. Download an installer or extract a.zip, run the app, and it launches a local web server on your machine. No Docker, no server config, no networking. This is the fastest way to try it. Second, the browser version: Same thing, but no installation. You can run Stirling in a web browser on a server and access it remotely. Third, managed hosting: Stirling offers a cloud option (SaaS) so you do not have to run infrastructure at all, but that defeats the privacy argument.
For most self-hosted use, you will choose Docker or Kubernetes. Docker gives you a container you deploy on a single machine. Kubernetes lets you scale across multiple nodes, add load balancing, and integrate with your existing cluster orchestration. Both take 5-15 minutes to set up if you are familiar with the tools.
Which should you pick? Desktop if you are testing. Docker if you are running it internally for a small team. Kubernetes if you have multiple teams, need high availability, or are building a platform service. Managed hosting if you do not want to run anything.
Install Stirling PDF Self-Hosted (Docker Quick Start)
The fastest way to run Stirling PDF on a Linux or macOS machine is Docker. Here is what you do.
First, pull the latest image:
docker run -d -p 8080:8080 --name stirling-pdf stirlingtools/stirling-pdf:latest
That is it. The container starts, binds to port 8080, and your Stirling instance is running. You can upload a PDF, merge files, extract text, whatever you need. No configuration file, no environment variables, no secrets to manage.
If you want persistence (so files survive a container restart), add a volume:
docker run -d -p 8080:8080 -v stirling-pdf-data:/uploads --name stirling-pdf stirlingtools/stirling-pdf:latest
Now /uploads inside the container maps to a Docker named volume. Your uploaded files stay even after the container stops.
If you are deploying to a remote server and want HTTPS (you should), put Stirling behind a reverse proxy like Nginx or Traefik. Create an Nginx server block that listens on port 443 with your SSL certificate, then configure it to forward requests to the Stirling container running on the internal port. This way, users access your domain over HTTPS while Stirling runs on the local server:
server {
listen 443 ssl;
server_name stirling.example.com;
ssl_certificate /etc/letsencrypt/live/stirling.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/stirling.example.com/privkey.pem;
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
Point the proxy destination to your Docker container, and Nginx will forward all traffic while keeping files on your server.
Docker Compose gives you a cleaner way to manage this if you are running multiple containers. Create a docker-compose.yml:
version: '3'
services:
stirling:
image: stirlingtools/stirling-pdf:latest
ports:
- "8080:8080"
volumes:
- stirling-data:/uploads
environment:
- DEBUG=false
volumes:
stirling-data:
Then docker-compose up -d and the same thing happens. This is the method most teams use because it is repeatable and version-controllable.
Self-Hosted Setup Deep Dive (Kubernetes and Production)
If you are running Stirling on Kubernetes, the architecture is similar but you need to think about StatefulSets, PersistentVolumeClaims, and service discovery.
Stirling itself is stateless: you can spin up two replicas and load-balance traffic between them. Files go into a shared PersistentVolume so both replicas see the same uploads. Here is a basic Kubernetes manifest:
apiVersion: apps/v1
kind: Deployment
metadata:
name: stirling-pdf
spec:
replicas: 2
selector:
matchLabels:
app: stirling-pdf
template:
metadata:
labels:
app: stirling-pdf
spec:
containers:
- name: stirling
image: stirlingtools/stirling-pdf:latest
ports:
- containerPort: 8080
volumeMounts:
- name: data
mountPath: /uploads
volumes:
- name: data
persistentVolumeClaim:
claimName: stirling-pvc
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: stirling-pvc
spec:
accessModes:
- ReadWriteMany
resources:
requests:
storage: 100Gi
---
apiVersion: v1
kind: Service
metadata:
name: stirling-pdf
spec:
selector:
app: stirling-pdf
ports:
- port: 80
targetPort: 8080
type: LoadBalancer
Deploy this, and Kubernetes creates two replicas, mounts a 100GB shared volume, and exposes a LoadBalancer service. Scale replicas up or down with kubectl scale deployment stirling-pdf --replicas=5, and Kubernetes handles the rest.
One caution: the PersistentVolume must support ReadWriteMany (simultaneous write access from multiple pods). Most cloud providers offer NFS or EBS volumes for this. On premises, you might use NFS-Server or Ceph. Without shared storage, your replicas will step on each other is files are uploaded to multiple pods. Plan for that.
Memory and CPU are modest. A single Stirling pod uses 300-500MB RAM at rest and spikes during OCR or large-file conversions. Start with 1 CPU and 512MB per replica, then adjust based on your workload. Stagger replicas across nodes for high availability.
Privacy and Security: What Changes When You Self-Host?
This is the core reason most people choose Stirling PDF over Smallpdf or iLovePDF. Your PDFs never leave your server. Period.
When you use Smallpdf, you upload a file to Smallpdf's servers (hosted on AWS or similar). Smallpdf decrypts it, processes it, and returns the result. At every step, your data is on someone else's hardware. Even if Smallpdf deletes the file after 24 hours (they claim they do), their backup systems, activity logs, and incident-response procedures all have copies. If a Smallpdf engineer needs to debug an issue, they can access your file. If a data breach occurs, your PDF is at risk.
With Stirling running on your laptop or your company server, that entire supply chain vanishes. The PDF sits on your storage. The processing happens in your CPU. The result lands in your /uploads folder. No third party touches it. No cloud provider logs it. No foreign government can subpoena it from a U.S. SaaS company.
This matters for sensitive documents: tax returns, medical records, contracts with confidentiality clauses, designs you want to keep proprietary. If your compliance auditor asks "Where are our PDFs processed?", the answer is "On our server, fully under our control."
There is a caveat: Stirling PDF does not encrypt files at rest by default. If your server is compromised, an attacker can read the files in /uploads. If compliance requires encryption, you need to add it yourself: either encrypt the PersistentVolume in Kubernetes, or run your storage on an encrypted filesystem (LUKS on Linux, FileVault on macOS). Stirling handles the security boundary between your app and the internet, but not the security of the storage itself.
Audit logging is another story. Free Stirling does not log every operation. If a paid Server tier is active (rarely deployed), it logs admin actions. For compliance purposes, if you need to prove "User X extracted text from Document Y at time Z", you have to add your own logging layer (maybe a sidecar container that watches /uploads) or run Stirling behind a WAF (web application firewall) that logs HTTP requests.
Common Use Cases and Operational Challenges
Stirling PDF shines in a few scenarios. First, batch processing: you have a folder of 500 invoices that need to be converted from PDF to PNG so they can be fed into an OCR pipeline. Stirling's API (available on paid tiers, or via scripted web requests) lets you automate this without touching a UI. Second, compliance workloads: your company handles HIPAA-regulated medical forms, and your security policy forbids cloud uploads. Stirling running on your server satisfies the audit. Third, internal tools: you are building an app that needs to merge user-uploaded PDFs, and you do not want to depend on an external API or pay per request.
The challenges emerge at scale. Stirling is single-threaded by default for heavy operations like OCR. If 10 users upload 100-page PDFs for OCR at the same time, they queue up. OCR is CPU-intensive; on a single machine, you get a 1-2 hour backlog. Kubernetes helps here: scale to 10 replicas and you have parallelism, but you need the infrastructure and the operational overhead.
Memory is another pinch point. Converting a 500MB TIFF image to PDF can require 1-2GB of RAM. If you deploy Stirling on a micro instance (1GB RAM), you will hit out-of-memory errors. Run it on bigger machines or use Kubernetes to auto-scale replicas when memory pressure rises.
Docker updates and security patches require manual restarts. If a vulnerability is found in the Stirling base image, you pull the latest image, stop the container, and restart it. During that window (usually < 1 minute), the tool is offline. For high-availability setups, run multiple replicas behind a load balancer so users do not notice the restart.
When to Move to Managed Hosting
Stirling PDF self-hosting works until it does not. You reach a point where the operational burden outweighs the savings. Here is when that happens.
First, when you need 24/7 uptime SLA. Self-hosting requires you to monitor the service, patch it, restart it, and troubleshoot failures. If a Docker image has a memory leak and crashes after 7 days, you are paged at midnight. If you do not have a Kubernetes setup, there is no auto-restart. Managed hosting means someone else handles that.
Second, when your team grows beyond one person. The first person gets Stirling working. The second person asks for a UI to upload files. The third person wants audit logs. The fourth person needs to know who processed which file. Suddenly you are building access control, authentication, and admin dashboards on top of Stirling. At that point, you have outgrown the free tier and are building a custom platform. Managed hosting includes all of this out of the box.
Third, when you need compliance documentation. If your SOC 2 auditor asks "Who maintains this service? What is their incident response plan? Do they have backups?", you have to answer as yourself. If the service is managed by a vendor, the vendor's audit report answers these questions. It is a burden lift.
Fourth, when file volume exceeds your infrastructure budget. 10 PDFs per day: laptop Stirling. 100 per day: a small VPS. 10,000 per day: you need a Kubernetes cluster, monitoring, alerting, and a half-time engineer to keep it running. At that scale, managed hosting is cheaper than your salary.
If you recognize yourself in any of these, it is time to explore managed Stirling PDF options. The transition is smooth: export your config, point to the new host, and existing workflows keep running.
Frequently Asked Questions
Is there a free, open-source PDF viewer available?
Yes. Stirling PDF is free and open-source for self-hosted use. The MIT license covers all 50+ PDF tools: merge, split, OCR, compression, watermarking, signing, and redaction. You pay nothing if you deploy it yourself. Cloud-based alternatives like Smallpdf and iLovePDF charge per operation or per month.
Is Stirling PDF safe to use?
Stirling PDF is as safe as any self-hosted software. The code is open-source, so security researchers can audit it. 96,900 GitHub stars indicate community scrutiny. That said, you are responsible for running it securely: use HTTPS, limit network access, keep the Docker image updated, and monitor logs for suspicious activity. The tool itself does not steal data, but misconfiguration creates risk.
Is Stirling PDF free?
Yes, completely. The core toolkit is MIT-licensed and costs nothing to self-host. Paid tiers (Server and Enterprise) add admin dashboards, user management, and audit logging, but free users get all 50+ PDF operations. There is no trial period or feature expiration. Free is not a trial; it is permanent.
What is Stirling PDF?
Stirling PDF is an open-source PDF toolkit that you deploy on your own server or laptop. It includes 50+ operations: merge, split, rotate, crop, compress, convert, OCR, watermark, sign, and redact. You access it via a web browser. No cloud upload, no recurring cost, no data residency risk.
How good is Stirling PDF?
Stirling PDF is good at what it does: running locally without cloud dependency. 30M+ downloads and 55,000 companies attest to that. It is not a replacement for Photoshop or InDesign; it is a no-frills PDF tool. Stability is high for simple operations (merge, split, rotate). OCR and large-file processing are slower on small instances. Speed improves with more CPU and replicas in Kubernetes.
Is Stirling PDF open-source?
Partially. The core code is MIT-licensed and open-source. Some modules (admin dashboards, SSO, audit logging) are proprietary and available only on paid Server or Enterprise tiers. You can read the full LICENSE file on GitHub to see which directories are free and which are not.
The Bottom Line
Stirling PDF is a mature, free, open-source PDF toolkit that solves a real problem: processing PDFs without sending them to cloud servers. If you need compliance control, offline capability, or simply prefer not to rely on SaaS pricing, self-hosting is straightforward. Docker gets you running in under a minute; Kubernetes scales it for high traffic.
The operational burden grows as your workload grows. At some point, managing your own infrastructure costs more than it saves. When that happens, managed Stirling PDF options can take that burden away while keeping your files local and secure. For now, download and try the free version: it costs nothing and your files stay yours.