Run JPedal with Docker
Table of contents
- Prerequisites
- Run JPedal with Docker
- Passing JVM flags
- Wrapping it in a shell alias or script
- Frequently asked questions
JPedal is distributed as a self-contained JAR, so you can run it inside any standard Java image without building a custom Docker image. This page shows how to run JPedal with Docker by mounting the JAR into the official eclipse-temurin image and treating docker run as a wrapper around java -jar.
This is useful if you want to run JPedal on a machine that doesn’t have Java installed, or to pin an exact Java version without changing the rest of the system.
Looking to run JPedal as a REST web service instead? See How to run the JPedal Docker Image, which uses our prebuilt microservice image.
Prerequisites
- Install Docker
- You must download jpedal.jar
- A Java 17+ image such as
eclipse-temurin:25-jre, which Docker pulls automatically on first run
Run JPedal with Docker
The command below mounts two things into the container: the JPedal JAR, and the directory containing your files. Replace /path/to/jpedal.jar with the location of the JAR on your machine, and /path/to/data with the directory holding your input files.
docker run --rm \
-v /path/to/jpedal.jar:/app/jpedal.jar \
-v /path/to/data:/data \
eclipse-temurin:25-jre \
java -jar /app/jpedal.jar --convert "/data/input.pdf" /data/output PNG
Breaking this down:
-v /path/to/jpedal.jar:/app/jpedal.jarmounts the JPedal JAR into the container at/app/jpedal.jar.-v /path/to/data:/datamounts your files into the container at/data, so input and output paths are given relative to/data. The converted output is written back to this directory on your machine.--rmremoves the container once the conversion finishes.
Because both the JAR and your files are mounted at runtime, there is no image to rebuild. To use a different version of JPedal, just point the first -v at a different JAR.
Windows: use a Windows-style path for the mounts (for example
C:\path\to\data:/data), and either put the whole command on one line or replace the\line-continuation character with a backtick`(PowerShell) or a caret^(Command Prompt).
Linux: files written to the mounted directory will be owned by
root. To have the output owned by your own user instead, add--user $(id -u):$(id -g)to the command. This isn’t needed on Docker Desktop for Windows or macOS.
Passing JVM flags
You can pass JVM flags and JPedal system properties before -jar, exactly as you would when running locally. For example, to increase the heap size:
docker run --rm \
-v /path/to/jpedal.jar:/app/jpedal.jar \
-v /path/to/data:/data \
eclipse-temurin:25-jre \
java -Xmx2g -jar /app/jpedal.jar --convert "/data/input.pdf" /data/output PNG
The JPedal settings and system properties (-D...) you can pass are the same as when running the JAR directly — see Running JPedal from the command line for full details.
Wrapping it in a shell alias or script
Typing the full command every time is tedious. On Linux and macOS you can wrap it in a shell alias so you only type the JPedal arguments. This alias uses $(pwd) to mount whichever directory you run it from:
alias jpedal='docker run --rm -v /path/to/jpedal.jar:/app/jpedal.jar -v "$(pwd)":/data eclipse-temurin:25-jre java -jar /app/jpedal.jar'
Then run conversions from any directory with just:
jpedal --convert "/data/input.pdf" /data/output PNG
Add the alias line to your ~/.bashrc or ~/.zshrc to make it permanent.
For something more portable, save it as a script instead, for example at /usr/local/bin/jpedal:
#!/usr/bin/env bash
docker run --rm \
-v /path/to/jpedal.jar:/app/jpedal.jar \
-v "$(pwd)":/data \
eclipse-temurin:25-jre \
java -jar /app/jpedal.jar "$@"
Make it executable with chmod +x /usr/local/bin/jpedal, then run conversions from any directory:
jpedal --convert "/data/input.pdf" /data/output PNG
(These wrappers are Bash/Zsh shorthands. On Windows, run the full docker run command shown above, or create a PowerShell function.)
Frequently asked questions
JPedal can’t find my input file
Paths are resolved inside the container, not on your host machine. The -v /path/to/data:/data mount makes your files available at /data, so input and output paths must be given relative to /data (for example /data/input.pdf) — not the path the file has on your machine. Make sure the file you want to convert is inside the directory you mounted.
Why mount the JAR instead of building a custom image?
Mounting keeps things simple: there’s no image to build, and you can switch JPedal versions just by pointing at a different JAR. If you would rather have a self-contained image — for CI or deployment — write a small Dockerfile:
FROM eclipse-temurin:25-jre
COPY jpedal.jar /app/jpedal.jar
ENTRYPOINT ["java", "-jar", "/app/jpedal.jar"]
Build it with docker build -t my-jpedal ., then run it with your files mounted at /data.
Do I have to use the eclipse-temurin:25-jre image?
No. JPedal requires Java 17 or later, so any image that provides a compatible JRE will work. We default to the Java 25 image, eclipse-temurin:25-jre, because it is small, official and up to date, but you can use an Alpine variant for a smaller image, or another vendor’s Java image — as long as it is Java 17+. See which Java versions JPedal supports for compatibility details.
Can I run JPedal as a web service?
This setup runs a single conversion and then exits, which is ideal for scripts and one-off jobs. To run JPedal as a long-running REST service, use our prebuilt Docker image instead — see How to run the JPedal Docker Image.
Do I need to install fonts?
When a PDF embeds its fonts, JPedal uses those and the rendered output is unaffected. If a PDF relies on fonts that are not embedded, JPedal falls back to the fonts installed on the system — and the eclipse-temurin images ship with fontconfig but no actual font files, so text in those documents may appear with missing or substituted glyphs. To fix this, install the fonts you need in a custom image, for example by adding RUN apt-get update && apt-get install -y fonts-dejavu to a Dockerfile based on the one above.