Installation
This guide covers all the ways to install PDFStract, from simple pip installation to development setups with Docker.
Installation Tiers
PDFStract offers tiered installation based on the libraries you need:
| Tier | Libraries | Install Command | Best For |
|---|---|---|---|
| Base | pymupdf4llm, markitdown | pip install pdfstract | Fast extraction, simple PDFs |
| Standard | pytesseract, unstructured | pip install pdfstract[standard] | OCR support, structured docs |
| Advanced | marker, docling, paddleocr, deepseek | pip install pdfstract[advanced] | Best quality, ML-powered |
| All | All libraries combined | pip install pdfstract[all] | Complete RAG pipeline |
Basic Installation
Using pip (Recommended)
# Base - Fast extractors only (pymupdf4llm, markitdown)
pip install pdfstract
# Standard - Adds OCR libraries (pytesseract, unstructured)
pip install pdfstract[standard]
# Advanced - Adds ML-powered libraries (marker, docling, paddleocr, deepseek)
pip install pdfstract[advanced]
# All - All converters combined (standard + advanced)
pip install pdfstract[all]
Using uv (Fast)
uv pip install pdfstract[all]
Development Installation
From Source
For the latest features or to contribute:
# Clone the repository
git clone https://github.com/aksarav/pdfstract.git
cd pdfstract
# Install in development mode
pip install -e .
# Or with uv
uv sync
With All Dependencies
To install with all libraries for development:
git clone https://github.com/aksarav/pdfstract.git
cd pdfstract
# Install full version in dev mode
pip install -e ".[full]"
What's Included in Each Tier
Base (Default)
Libraries visible in dropdown:
- pymupdf4llm - Fast, lightweight PDF extraction
- markitdown - Microsoft's markdown converter
pip install pdfstract
Standard
All Base libraries plus:
- pytesseract - OCR for scanned PDFs (requires system tesseract)
- unstructured - Smart document parsing
pip install pdfstract[standard]
Advanced
All Standard libraries plus:
- marker - ML-powered, excellent for complex layouts
- docling - IBM's document intelligence platform
- paddleocr - Accurate OCR engine
- deepseek - GPU-accelerated OCR
pip install pdfstract[advanced]
Full
All Standard + Advanced libraries combined:
pip install pdfstract[all]
Chunking support (10+ methods via chonkie) is included in the base installation. No extra install needed!
Docker Installation
Using Make ( With Docker ) (Recommended)
The easiest way to get everything running with all libraries including MinerU:
why do we need make instead of direct docker ? we are downloading the necassary models from hugging face in your host machine as docker containers have limited bandwidth and memory If you check the docker-compose.yaml you can find that we are mounting these models as a volume for smoother docker setup.
# Clone the repository
git clone https://github.com/aksarav/pdfstract.git
cd pdfstract
# Download models and start services (first time)
make up
# Or step by step:
make models # Download HuggingFace/MinerU models (~10GB)
make build # Build Docker images
make up # Start services
Available Make Commands
| Command | Description |
|---|---|
make up | Build and start all services |
make down | Stop all services |
make logs | View container logs |
make status | Show running containers |
make rebuild | Rebuild and restart |
make clean | Remove containers and volumes |
make models | Download ML models only |
This starts:
- Web UI at http://localhost:3000
- API server at http://localhost:8000
Using Docker Images
Pull and run individual components:
# Pull the latest image
docker pull aksarav/pdfstract:latest
# Run as a web service
docker run -p 8000:8000 aksarav/pdfstract:latest web
# Run CLI commands
docker run -v $(pwd):/workspace aksarav/pdfstract:latest convert /workspace/document.pdf
Verification
Test your installation:
import pdfstract
# Check version
print(f"PDFStract version: {pdfstract.__version__}")
# List available converters
pdfstract = pdfstract.PDFStract()
print("Available converters:", pdfstract.list_converters())
print("Available chunkers:", pdfstract.list_chunkers())
Or from command line:
# Check installation
pdfstract --version
# List available tools
pdfstract list-converters
pdfstract list-chunkers
System Requirements
Recommended Requirements
- Python 3.11+
- 8GB RAM (for large documents)
- 5~10GB disk space (for all libraries to download)
- GPU (OPTIONAL for GPU Only models)
Platform Support
| Platform | Status | Notes |
|---|---|---|
| Linux | ✅ Full | All features supported |
| macOS | ✅ Full | All features supported |
| Windows | ✅ Full | All features supported |
Troubleshooting
Common Issues
ImportError: No module named 'pdfstract'
# Make sure you're in the right environment
pip list | grep pdfstract
# Reinstall if needed
pip uninstall pdfstract
pip install pdfstract
Converter not found errors
# Install advanced tier for ML-powered converters (marker, docling, etc.)
pip install pdfstract[advanced]
# Or install everything
pip install pdfstract[all]
Memory errors with large PDFs
# Use streaming mode
pdfstract convert large.pdf --streaming
# Or process in chunks
pdfstract convert large.pdf --max-pages 10
Environment Issues
Virtual Environment (Recommended)
# Create virtual environment
python -m venv pdfstract-env
source pdfstract-env/bin/activate # Linux/Mac
# pdfstract-env\Scripts\activate # Windows
pip install pdfstract
Conda Environment
# Create conda environment
conda create -n pdfstract python=3.10
conda activate pdfstract
pip install pdfstract
GPU Support
GPU acceleration is available with the advanced or all tiers (includes PyTorch):
# Advanced tier includes GPU-capable libraries
pip install pdfstract[advanced]
# Verify GPU detection
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"
For CUDA support, ensure you have the appropriate PyTorch version installed for your CUDA version.
Next Steps
Once installed, try these guides:
- Quick Start - Convert your first PDF
- Python Module - Use in your applications
- CLI Guide - Command-line usage
- Web UI - Visual interface
Need help? Check our GitHub Issues or start a Discussion!