PDF2EPUB 📚

Convert PDF files to nicely structured Markdown and EPUB format with intelligent layout detection.

✨ Features

• 📖 Smart layout detection for books and academic papers
• 🔍 Advanced text extraction and OCR capabilities
• 📊 Table detection and formatting
• 🖼️ Image extraction and optimization
• 📝 Clean markdown output with preserved structure
• 📱 EPUB generation with customizable styling
• 🌍 Multi-language support
• 🚀 GPU acceleration support (NVIDIA & AMD)
• 🍎 Apple Silicon support

🛠️ Dependencies

• Python 3.10–3.14 (3.13 recommended, see below)
• PyTorch (with CUDA/ROCm support for GPU acceleration)
• marker-pdf==1.10.2
• transformers==4.57.6
• markdown==3.10.2
• latex2mathml==3.81.0

⚠️ Python version

Python 3.13 is recommended.

marker-pdf constrains Pillow<11.0.0, and Pillow only ships Python 3.14 wheels from 11.3.0 onward. On Python 3.10–3.13 every dependency installs as a prebuilt wheel. On 3.14, pip has to build Pillow from source instead: this works, but it is slower and requires a working C toolchain plus the image library headers Pillow links against. On Debian/Ubuntu install them first:

sudo apt install libjpeg-dev zlib1g-dev libtiff-dev libfreetype6-dev libwebp-dev

Without these headers the install fails with RequiredDependencyException: The headers or library files could not be found for jpeg.

💻 Installation

1. Create and activate a virtual environment.

On Linux/Mac:

python3.13 -m venv .venv
source .venv/bin/activate

On Windows:

py -3.13 -m venv .venv
.venv\Scripts\activate

2. Install Python dependencies (this installs PyTorch as well):

pip install -r requirements.txt

3. GPU acceleration (optional):

PyTorch is installed as a dependency in step 2. On Apple Silicon that wheel already supports MPS, so no further action is needed. For a specific CUDA or ROCm build, reinstall PyTorch using the selector at pytorch.org/get-started/locally. For example, for AMD GPUs with ROCm:

pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.2

4. Verify GPU support:

import torch
print(torch.__version__)  # PyTorch version
print(torch.cuda.is_available())  # Should return True for NVIDIA
print(torch.backends.mps.is_available())  # Should return True for Apple Silicon
print(torch.version.hip)  # Should print ROCm version for AMD

🐳 Docker

A CPU-only image can be built from the included Dockerfile:

docker build -t pdf2epub .

Run it with your PDFs mounted at /data and a model cache volume (marker-pdf downloads its models on first run):

docker run -it --rm \
  -v "$(pwd)":/data \
  -v pdf2epub-models:/models \
  pdf2epub input.pdf

-it is required for EPUB generation because metadata is prompted interactively; with --skip-epub it can run non-interactively.

Tagged releases are also published to ghcr.io/overcuriousity/pdf2epub by the Docker workflow.

🚀 Usage

Basic Usage

Convert a single PDF file:

python main.py input.pdf

Convert all PDFs in a directory:

python main.py input_directory/

EPUB generation prompts interactively for metadata (title, author, language, and so on; press Enter to accept each default). It therefore needs a terminal — run it non-interactively and it will fail with EOFError. Use --skip-epub to produce only markdown without any prompts.

Advanced Options

python main.py [input_path] [output_path] [options]

Options:
  --max-pages INT          Maximum number of pages to process
  --start-page INT         Page number to start from
  --skip-epub              Skip EPUB generation, only create markdown
  --skip-md                Skip markdown generation, use existing markdown files

If input_path is omitted, all PDFs in ./input/ are processed.

Examples

Process a specific range of pages:

python main.py book.pdf --start-page 10 --max-pages 50

Convert to markdown only:

python main.py thesis.pdf --skip-epub

Output Structure

output_directory/
├── document_name/
│   ├── document_name.md
│   ├── document_name.epub
│   ├── document_name_metadata.json
│   └── images/
│       ├── image1.png
│       ├── image2.jpg
│       └── ...

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a new branch for your feature
3. Commit your changes
4. Push to your branch
5. Create a Pull Request

Please ensure your code follows the existing style and includes appropriate tests.

Development Setup

1. Clone the repository:

git clone https://github.com/overcuriousity/pdf2epub.git
cd pdf2epub

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

3. Install development dependencies:

pip install -r requirements.txt

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🐛 Known Issues

• Some image embedding might need manual adjustment
• Some complex mathematical equations might not be perfectly converted
• Certain PDF layouts with multiple columns may require manual adjustment
• Font detection might be imperfect in some cases

🙏 Acknowledgments

This project builds upon several excellent open-source libraries:

• marker-pdf for PDF processing
• mark2epub for markdown conversion
• PyTorch for GPU acceleration
• Transformers for advanced text processing