Skip to content

Installation

Jump to bottom
Retro-Jack edited this page Aug 6, 2026 · 2 revisions

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.

GPU acceleration

The published image ships a CUDA build of PyTorch (torch 2.13.0+cu130), so an NVIDIA card can do the model work instead of the CPU. Measured on an RTX 4070 Ti: an 8-page document went from 90 seconds to 10, and a 77-page scan's layout pass from roughly 9 seconds per page to 34 pages per second.

Two things are needed, and Epubify handles the second for you.

1. The NVIDIA container runtime (you)

sudo pacman -S nvidia-container-toolkit        # Arch/CachyOS
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Without it, docker run --gpus all fails outright. Epubify probes once at startup and, if the runtime is missing, prints these commands and carries on using the CPU rather than failing the run. Set USE_GPU=false to skip the probe entirely.

2. A compiler in the image (Epubify)

PyTorch compiles its GPU kernels at runtime through Triton, and Triton shells out to a C compiler that the upstream image doesn't contain. A GPU run on the stock image therefore dies with Failed to find C compiler before the first page — while CPU runs, which never take that path, work fine.

Dockerfile.gpu (beside the script) adds gcc to the upstream image and nothing else. Epubify builds it automatically the first time a GPU run needs it, tagging it epubify/pdf2epub:gpu. A failed build isn't fatal — it falls back to the CPU.

Clone this wiki locally