MegaParse: document parsing aimed at what a model can read

What the parser is optimising for

MegaParse is described as a parser for every type of document, handling text, PDFs, PowerPoint presentations and Word documents, with the stated focus on having no information loss during parsing. The repository description is blunter about the audience: it is a file parser optimised for LLM ingestion.

The design goal follows from that. A parser aimed at people can afford to flatten a document into a readable sequence, but a parser aimed at a model has to keep the structure that carries meaning, because a table flattened into a run of text loses the relationship between its cells, and a heading that becomes an ordinary line loses the document's hierarchy.

The README's support matrix lists the file types as PDF, PowerPoint and Word, and the content it aims to preserve as tables, the table of contents, headers, footers and images. The feature list adds Excel and CSV to the compatible formats, and open source and free to use as the licence terms, which are Apache-2.0.

The monorepo is the QuivrHQ project with its original logo and star history still in place, and the package version history shows megaparse releases at v0.0.55 on 2025-02-14 and v0.0.54 on 2025-02-11, with a separate megaparse-sdk package at v0.1.12.

Installation and the tools it expects on your machine

The package needs Python 3.11 or newer, and the install is the ordinary one:

pip install megaparse

What follows in the README is the part people miss, because the parser leans on system binaries rather than doing everything in Python. You need an OpenAI or Anthropic API key in a .env file, poppler installed on the machine for images and PDFs, tesseract for the same, and on a Mac, libmagic, installed with brew install libmagic.

Those four dependencies map onto the four hard problems in document parsing. Poppler renders PDF pages, which is what lets the parser treat a page as an image and as text. Tesseract is the optical character recognition pass for pages that carry no text layer at all, which is most scanned documents. libmagic identifies the file type from its content rather than its extension, so a mislabelled file is still routed correctly.

The container image exists precisely because of this list. The Dockerfile installs libmagic-dev, poppler-utils, tesseract-ocr, libreoffice, pandoc and a set of build tools, then runs playwright install with its dependencies and downloads the NLTK corpora, so that a running service has the whole stack without the operator assembling it.

Two paths: text parsing and the vision path

The plain usage is three lines. The parser is constructed, pointed at a file and asked to load it:

from megaparse import MegaParse

megaparse = MegaParse()
response = megaparse.load("./test.pdf")
print(response)

The second path, MegaParse Vision, changes who reads the page. Instead of extracting and reconstructing, it hands the document to a multimodal model:

from megaparse.parser.megaparse_vision import MegaParseVision

model = ChatOpenAI(model="gpt-4o", api_key=os.getenv("OPENAI_API_KEY"))
parser = MegaParseVision(model=model)
response = parser.convert("./test.pdf")

The README lists the models it supports as the multimodal ones, naming claude 3.5, claude 4, gpt-4o and gpt-4.

The distinction matters for cost and for behaviour. The text path runs locally and its output depends on poppler and tesseract doing their job. The vision path sends pages to a model, so a complex layout is interpreted rather than reconstructed, which handles tables and figures that defeat layout heuristics, at the price of a network call and a token bill on every document. The environment template lists the keys for it, with placeholders for an OpenAI key, a Llama Cloud key and a MegaParse API key.

The API service, and a port that does not line up

The project can run as a service, and the README is brief about it: there is a Makefile, run make dev at the root of the project, and the endpoints are documented at localhost:8000/docs.

The compose file shows how the service is actually launched, with uvicorn serving the API app under reload on port 8000 with the uvloop event loop, and the container exposing 8000 on 8000.

There is a small inconsistency worth noting. The healthcheck in the compose file curls http://localhost:5050/healthz, while the service listens on 8000 and the container port mapping is 8000 to 8000. As written, that healthcheck would not succeed against the running container, which matters if you rely on the health status to gate a deployment or a dependent service.

The compose file also adds host.docker.internal to the container's hosts file, with the host-gateway mapping, so that code running inside the container can reach services on the host, and the image is pulled with a pull policy of if_not_present.

Inside the container and the monorepo layout

The Dockerfile builds from python:3.11.10-slim-bullseye, installs the system dependencies and then does something particular with the workspace layout. It copies the lock file and the root project metadata first, then copies the per-library project metadata for libs/megaparse and libs/megaparse_sdk, installs the locked requirements with uv, runs the Playwright install and the NLTK downloader, and only then copies the rest of the source. Finally it installs the two libraries from their directories.

That ordering exists to make use of the layer cache. The dependency layers change far less often than the source, so a rebuild after a source change reuses the expensive layers instead of reinstalling LibreOffice and Tesseract every time.

The repository layout explains the monorepo structure. There is a libs/ directory holding the workspace members, a rye workspace configuration with members set to libs/*, a root pyproject.toml named megaparse-monorepo, and separate pyproject.toml files for the library and the SDK. The build backend is hatchling, pinned to an exact version, and the wheel target packages src/megaparse.

Around that are the directories a parser project needs: benchmark/, evaluations/, images/, docs/, a Dockerfile.gpu alongside the main one, docker-compose.dev.yml, and the usual .pre-commit-config.yaml, .flake8 and .vscode. The tooling is ruff with a line length of 88 and mypy, pytest with xdist and coverage, and the release process is handled by release-please with its own manifest and configuration files.

The benchmark, and how to argue with it

The README includes a benchmark table with a similarity_ratio column, and higher is better. MegaParse Vision scores 0.87, unstructured with a table check scores 0.77, plain unstructured scores 0.59 and llama_parser scores 0.33.

That is the project's own measurement of its value proposition: the vision path sits above the layout-based parsers, and the margin over the layout-based path with table checking is where the interesting work is. The README does not describe what the ratios are computed against, so the numbers are best read as a ranking rather than as an absolute score.

What is more interesting is the invitation attached to it. The README asks anyone who wants to evaluate and compare their own module to add a configuration in evaluations/script.py and run python evaluations/script.py, and to open a pull request if the result is better. That is an unusual and generous arrangement for a project that is, in effect, competing with the module others are bringing in.

The same list of unfinished work is published in the README: improving the table checker, building checkers for modular postprocessing, and adding structured output so the parser can be talked to programmatically rather than only read.

Where the project stands

The version numbers tell part of the story. The megaparse package is at 0.0.55 and the SDK at 0.1.12, both published in February 2025, and the last push to the repository was on 2026-10-15. The releases and the development activity are therefore far apart, which for a project whose distribution is a pip package means most installs are of a build from more than a year ago.

The package is still pre-1.0, and the README describes it as under construction with three named work items. For a parser, that is not unusual, because the shape of a good output for model ingestion is still moving, but it does mean the interface may change between versions.

The licence is Apache-2.0, which makes it usable inside commercial products without copyleft obligations, and the model dependency is optional rather than baked in: the text path needs no model at all, only the system tools, so a team with strict data handling rules can keep documents on its own infrastructure and use the vision path only where it earns its cost.

Editorial conclusion

MegaParse suits a team whose documents fail to reach a model in a usable shape, especially when tables and headers are the part being lost, and who can accept a Python dependency plus poppler, tesseract and libmagic on the host. It is the wrong choice if you need a stable interface across upgrades, since the package is still at 0.0.55 and the release list stops in February 2025, and the wrong choice if documents cannot leave your infrastructure, since the vision path calls a hosted model. Verify first that the parser reproduces your own documents faithfully, that the container healthcheck points at the port your service actually listens on, and that the vision path costs you less than the layout-based path on your workload.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. The-Vibe-Company/megaparse on GitHub