Installation

Installation

Requirements

Requirement	Notes
Docker	The conversion runs in a container. The daemon must be running, and your user should be in the docker group — otherwise run the script with sudo.
perl	Used for filename cleanup. Standard on most Linux systems.
timeout	Used when present, to cap runaway conversions. Part of coreutils.

Everything else the script uses (find, sed, basename, mv, cp) is standard on any Linux system.

Setup

1. Put epubify.sh somewhere on your system and make it executable:

   chmod +x epubify.sh

2. Edit the variables at the top of the script — at minimum INPUT_DIR, STAGING_DIR and OUTPUT_DIR. See Configuration.

3. Create your input folder. INPUT_DIR must already exist — the script checks it and stops if it doesn't. Staging, output and the model cache are all created for you.

First run

Two large one-off downloads happen the first time:

• The container image. ghcr.io/overcuriousity/pdf2epub:latest is pulled automatically if it isn't already present locally. If the pull fails, set BUILD_CONTEXT to a clone of the pdf2epub repository and the script builds the image itself instead of giving up.
• The models. pdf2epub downloads its layout and OCR models on first conversion. They're kept in MODEL_CACHE and reused afterwards.

MODEL_CACHE is a bind mount rather than a named Docker volume on purpose: the container runs as your UID, and an empty named volume is created root-owned, which the container user then couldn't write to.

A note on the GPU

The published image ships a CPU PyTorch build, so a CUDA card sits idle no matter what — there's deliberately no --gpus flag in the script. For GPU acceleration, install pdf2epub natively with a CUDA PyTorch build instead of using this script.