Guide · Open source
How to use zerox: install, run and extract documents
Updated · written with AI from the project's own documentation and checked against our catalogue data
Zerox is an open-source package for Node.js and Python that converts documents such as PDFs, DOCX files and images into Markdown. It turns each page into an image, sends that image to a vision model such as GPT-4o, and joins the results. This guide shows you how to install the Node package, run a first conversion, and use the options that matter most.
Zeroxgetomni-ai/zerox · ★ 12.3k · MIT Install options & downloads Quick start
- 1Check prerequisites. Confirm Node.js is installed and you have an API key for a supported provider such as OpenAI.
- 2Install the package. Run npm install zerox in your project folder.
- 3Install GraphicsMagick. On Linux, run sudo apt-get update and sudo apt-get install -y graphicsmagick if PDF processing fails.
- 4Set your API key. Store the key in the OPENAI_API_KEY environment variable so it stays out of your code.
- 5Run a conversion. Call zerox with filePath and credentials, then read the Markdown from the result.
- 6Tune options. Limit pages with pagesToConvertAsImages and set concurrency to suit your rate limits.
What you need before you install zerox
Zerox is a package you call from code, not a desktop app. You need Node.js for the Node package, and Python with Poppler for the Python package. You also need an API key for a supported model provider, such as OpenAI.
The Node package uses GraphicsMagick and Ghostscript for PDF-to-image conversion. The README says these should be pulled in automatically, but you may need to install them yourself.
- Node.js (for the Node package)
- GraphicsMagick and Ghostscript (for PDF processing in Node)
- Python with Poppler (for the Python package)
- An API key for a supported model provider such as OpenAI, Azure OpenAI, AWS Bedrock or Google Gemini
Install zerox with npm and GraphicsMagick
Install the Node package with npm. If PDF processing fails, install GraphicsMagick. The README gives the Linux command below.
npm install zerox
sudo apt-get update
sudo apt-get install -y graphicsmagickRun your first conversion
Import zerox and pass it a file path or a file URL, along with your credentials. The README shows the API key being read from the OPENAI_API_KEY environment variable. The result contains the Markdown for each page.
For a local file, resolve its path first, as the README example does. The example output in the README includes per-page content, a page count and token counts.
- Use filePath for a local path or a URL to the file
- Pass your key under credentials.apiKey
import { zerox } from "zerox";
import path from "path";
const result = await zerox({
filePath: path.resolve(__dirname, "./cs101.pdf"),
credentials: {
apiKey: process.env.OPENAI_API_KEY,
},
});Tune the most useful options
The README lists many optional settings. Start with a few that control cost, speed and output. Set pagesToConvertAsImages to convert only some pages, and concurrency to control how many pages run at once.
maintainFormat passes the output of one page into the request for the next. The README says this is slower because requests run synchronously, but it helps with tables that cross pages.
- pagesToConvertAsImages: a page number, an array such as [1, 2, 3], or -1 for all pages
- concurrency: number of pages to run at a time
- model and modelProvider: choose the model and provider
- maintainFormat: slower, but more consistent formatting across pages
- cleanup: clears images from the temp directory after the run
- outputDir: saves the combined result.md to a folder
Extract structured data with a JSON Schema
To pull specific fields instead of full Markdown, set extractOnly to true and provide a schema. The README says the schema follows the JSON Schema standard. Set extractPerPage to extract from each page rather than the whole document at once.
You can use a different model for extraction by setting extractionModel, extractionModelProvider and extractionCredentials. By default the same model is used.
const result = await zerox({
filePath: "path/to/file",
credentials: { apiKey: process.env.OPENAI_API_KEY },
extractOnly: true,
schema: { /* your JSON Schema */ },
});What people use it for
- Preparing PDFs with tables and charts for an AI or search system
- Converting invoices or scanned forms into Markdown, as in the README example
- Pulling structured fields from documents with a JSON Schema
- Processing DOCX files and images into text for ingestion pipelines
Frequently asked questions
Is zerox free to use?
The package is MIT licensed, so you can use and modify the code. Each page is sent to a model provider you pay for, so you still pay per-page model API costs.
Does zerox need an OpenAI API key?
You need an API key for a supported model provider. The README uses OpenAI in its examples, and it also lists Azure OpenAI, AWS Bedrock and Google Gemini.
What do I need to install zerox for PDFs?
In Node, PDF processing uses GraphicsMagick and Ghostscript. In Python, it uses Poppler. The README says the Node dependencies should install automatically but may need manual install.
Is there a no-code version of zerox?
The README describes an SDK used in code. The only non-coding option it mentions is the hosted demo at getomni.ai/ocr-demo.
Can zerox work offline?
The README does not describe local or offline models. Zerox sends page images to hosted vision models, so it is not designed for offline processing.
How does zerox compare with Marker, Docling or Unstructured?
The README does not compare zerox with other tools. Marker, Docling, Unstructured and MinerU are listed as comparable projects, so test each on your own documents before choosing.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Zerox suits developers who already have model API access and need Markdown or structured data from documents with complex layouts. It is a poor fit for non-coders, teams that want to avoid per-page API costs, or anyone who needs offline, high-volume processing.
Install options & downloads