Skip to main content

​
Prerequisites

Before installing Zerox, ensure you have:
  • Node.js 14 or higher
  • npm, yarn, or pnpm package manager
  • System access to install dependencies (GraphicsMagick, Ghostscript)

​
Installation

1

Install the package

Install Zerox using your preferred package manager:
npm install zerox
The package includes a postinstall script that will attempt to automatically install system dependencies (GraphicsMagick, Ghostscript, LibreOffice, and Poppler).
2

Install system dependencies

Zerox requires GraphicsMagick and Ghostscript for PDF processing. These are typically installed automatically during the npm install process, but you may need to install them manually.
sudo apt-get update
sudo apt-get install -y graphicsmagick ghostscript
For processing non-PDF document formats (DOCX, XLSX, etc.), also install LibreOffice:
sudo apt-get install -y libreoffice
3

Verify installation

Create a test file to verify everything is working:
test-zerox.ts
import { zerox } from 'zerox';

async function test() {
  try {
    const result = await zerox({
      filePath: 'https://omni-demo-data.s3.amazonaws.com/test/cs101.pdf',
      credentials: {
        apiKey: process.env.OPENAI_API_KEY || 'your-api-key',
      },
    });
    console.log('Zerox is working!', result);
  } catch (error) {
    console.error('Installation error:', error);
  }
}

test();
Run the test:
npx ts-node test-zerox.ts
You’ll need a valid OpenAI API key (or another supported provider) to test the OCR functionality.

​
Verification Commands

Verify that system dependencies are correctly installed: 
# Check GraphicsMagick
gm -version

# Check Ghostscript
gs --version

# Check LibreOffice (optional, for non-PDF documents)
soffice --version
All commands should return version information without errors.

​
Troubleshooting

GraphicsMagick is not installed or not in your system PATH.Solution:
  • On Linux: Run sudo apt-get install -y graphicsmagick
  • On macOS: Run brew install graphicsmagick
  • On Windows: Download and install from the official website, then add to PATH
Ghostscript is not installed or not in your system PATH.Solution:
  • On Linux: Run sudo apt-get install -y ghostscript
  • On macOS: Run brew install ghostscript
  • On Windows: Download and install from ghostscript.com, then add to PATH
This is often caused by security policies in newer versions of Ghostscript or ImageMagick.Solution (Linux/macOS): Edit the Ghostscript policy file:
# Find the policy file
sudo find / -name "policy.xml" 2>/dev/null | grep ImageMagick

# Edit the file and add PDF permissions
sudo nano /etc/ImageMagick-*/policy.xml
Add or modify the PDF policy line:
<policy domain="coder" rights="read|write" pattern="PDF" />
The automatic dependency installation may fail if you don’t have sudo access.Solution:
  • Install system dependencies manually using the commands in Step 2
  • If using npm, you can skip the postinstall script with: npm install --ignore-scripts zerox
  • Then manually install the system dependencies
TypeScript types or module resolution issues.Solution:
# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Or with yarn
rm -rf node_modules yarn.lock
yarn install
Make sure your tsconfig.json has proper module resolution:
{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}
LibreOffice is required for non-PDF document formats.Solution: Install LibreOffice:
  • Linux: sudo apt-get install -y libreoffice
  • macOS: brew install --cask libreoffice
  • Windows: Download from libreoffice.org
Verify with: soffice --version

​
Dependencies Reference

Zerox uses the following system dependencies:
DependencyPurposeRequired
GraphicsMagickImage processing and PDF-to-image conversionYes
GhostscriptPDF rendering engineYes
LibreOfficeConvert DOCX, XLSX, PPT to PDFOptional
PopplerAlternative PDF utilitiesOptional

​
Next Steps

Quick Start

Start using Zerox with your first OCR document

Configuration

Configure models, providers, and processing options

Build docs developers (and LLMs) love

Get started for freeTalk to us