Parsr: turning PDFs, images and DOCX into structured JSON, Markdown and CSV

The gap Parsr fills between a PDF and a dataframe

A PDF is a page description, not a data structure. Text is placed at coordinates, columns are visual rather than semantic, and a table has no rows and columns until something decides where they are. Parsr targets that gap. The repository describes it as a minimal-footprint document cleaning, parsing and extraction toolchain for image, pdf, docx and eml input, producing JSON, Markdown, CSV or Pandas DataFrame, or TXT.

The audience named in the README is analysts, data scientists and developers who need what it calls clean structured and label-enriched information for downstream applications. In practice that means someone with a folder of supplier invoices, statements or scanned forms who wants rows in a database rather than a folder of files. Parsr is not a text extractor that returns a string blob. Its processing modules regenerate hierarchy at the word, line and paragraph level, and detect headings, tables, lists, tables of contents, page numbers, headers and footers, and links. The output is a document tree with labels, which is a different product from `pdftotext` and a different product from a cloud OCR API.

How the parsing pipeline is wired

The repository layout shows the shape of the system. `server/` holds the TypeScript core, `server/src/processing/` holds the processing modules, `api/` holds an API server, `clients/` holds client code, and `demo/` holds four examples: `doc-versioning`, `echo-module-py`, `parsr-jupyter-demo` and `vue-viewer`. The npm scripts confirm the split: `build:ts` compiles the core to `./dist`, `install:api` installs the API server separately, and `start:api` chains build, API install and start.

Parsing itself is a chain of modules, not a single model call. A document enters the API, is converted, and then passes through ordered processing steps that clean it and rebuild structure. The README points to `server/src/processing/README.md` for the current module list, which is where the actual behaviour lives. Third-party components do the heavy lifting: the dependency list names QPDF, ImageMagick, Pdfminer.six, PDF.js, Tesseract, Camelot, and optionally MuPDF and Pandoc. Camelot and Tesseract in that list tell you the intended split: vector PDFs go through geometry-based table detection, while scanned pages go through OCR. The pipeline is configurable, and `docs/configuration.md` is the reference for the options exposed in the GUI viewer.

The output is a single structured document, typically JSON, that later stages can query. That is the design bet: keep the parse deterministic and inspectable, and let your own code map the tree to your schema.

Installing Parsr with Docker and running a first document

The README calls Docker the quickest way to install and run the API. Pull the image first.

docker pull axarev/parsr

Start the API by publishing port 3001, which is the port the README uses.

docker run -p 3001:3001 axarev/parsr

The README states this launches the API on http://localhost:3001. From there the API guide in `docs/api-guide.md` describes the request format. If you prefer Compose, the repository ships a `docker-compose.yml` that starts the API and the GUI together, mounts `./pipeline/` into the container output directory, and exposes the UI on port 8080.

services:
  parsr:
    image: axarev/parsr
    ports:
      - 3001:3001
    environment:
      ABBYY_SERVER_URL:
    volumes:
      - ./pipeline/:/opt/app-root/src/api/server/dist/output
  parsr-ui:
    image: axarev/parsr-ui-localhost
    ports:
      - 8080:80

If you would rather drive it from Python, the README gives a client package and points at a Jupyter demo.

pip install parsr-client

The `demo/parsr-jupyter-demo` directory is the worked example for that client. For a first real run, start the GUI container as the README describes, open http://localhost:8080, upload one document, and inspect the JSON tree before writing any mapping code. The GUI is where the configurable options become visible; `docs/configuration.md` explains what each one does.

The maintenance warning is the first thing to read

The README opens with a warning block stating that the project is no longer maintained, that security patches are not being applied, and that an alternative such as LiteParse should be considered for a local Apache-2.0 parsing solution. The repository is not archived and the last push was on 2026-03-20, so the code is not untouched, but the project's own documentation tells you not to expect security work.

That changes what Parsr is. It is a frozen component you vendor, not a dependency you track. The release list reinforces the point: v1.2.2 dates from 2020-11-20, v1.2.1 from 2020-11-04, and V1.2.0 from 2020-10-02. Any bug you find in the parsing modules is yours to fix, and the module chain in `server/src/processing/` is written in TypeScript, so a fix is possible if you have the skills and the appetite. For a document set that changes shape every quarter, that is a real cost.

The second limitation is scope. Parsr is a parsing toolchain, not a document understanding system. It does not answer questions about a contract or classify an invoice. It gives you a labelled tree and stops. If your requirement is a field-level extraction with confidence scores, you are building that layer yourself on top of the JSON.

The third is the optional dependencies. MuPDF is listed as AGPL and Pandoc as GPL, both optional. Enabling them changes the licence surface of your deployment, and the README does not spell out which processing modules pull them in. Check `docs/dependencies.md` before you turn anything on.

Where Parsr sits against a cloud document API

The obvious alternative is a hosted document intelligence service, which returns fields rather than a page tree. The difference is not quality, it is where the model lives and who owns the schema. A hosted service decides what an invoice field is, updates that decision on its own schedule, and sees your documents. Parsr runs inside your network, on port 3001, and returns geometry and labels that you interpret. For documents that cannot leave your infrastructure, that is the whole argument.

The README itself names LiteParse as the alternative to consider for a local Apache-2.0 parsing solution. That is the honest comparison to make: another local parser, chosen by the maintainers as the successor path. If your reason for looking at Parsr is local Apache-2.0 parsing, evaluate both against the same sample set rather than assuming the older project is the safer one.

Against a plain PDF library, the trade-off runs the other way. A library such as PDF.js, which Parsr itself depends on, gives you text and coordinates with no opinion. Parsr adds the opinion: hierarchy, headings, tables, lists. You get more structure and less control, plus a Docker image, an API server and a module chain to operate.

Licence and upgrade cost of a frozen parser

Parsr is licensed under Apache 2.0, copyright 2020 AXA Group Operations S.A. That is permissive for the core, and it is the reason the README frames the project as usable in commercial settings. The dependencies are a mixed picture, and the README lists them explicitly: QPDF under Apache, ImageMagick under Apache 2.0, Pdfminer.six under MIT, PDF.js under Apache 2.0, Tesseract under Apache 2.0, Camelot under MIT, MuPDF under AGPL as an optional dependency, and Pandoc under GPL as an optional dependency. Whether AGPL or GPL components create obligations for your deployment depends on how you link and distribute them, and that is a question for your own counsel rather than for this article.

Upgrade cost is where the maintenance warning bites. With the newest listed release at v1.2.2 from 2020-11-20, there is no upgrade path to plan. The practical approach is to pin the image tag, keep the Compose file in your own repository, and treat the JSON output as an interface you own. The `docker-compose.yml` in the repository already mounts `./pipeline/` as the output directory, which makes it straightforward to keep parsed artefacts outside the container and to diff them when you change configuration. If a future CVE lands in ImageMagick or Tesseract, you are rebuilding the image yourself, because the README states patches are not being applied upstream.

Editorial conclusion

Adopt Parsr only if you want a self-hosted, Apache-2.0 parsing pipeline and can pin the axarev/parsr image, accept that security patches are not being applied, and keep the output contract inside your own code. Do not adopt it for regulated or internet-facing document intake, and do not plan around new features: the newest release listed is v1.2.2 from 2020-11-20. Before committing, run the docker-compose.yml stack against your own sample set and check how the configured modules handle your worst table and your worst scan, because the README does not document rollback or versioned output schemas.

Frequently asked questions

Official sources

1. axa-group/Parsr on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases