dedoc turns messy documents into one logical tree

One output tree instead of a parser per format

dedoc is presented as an open universal system for converting documents to a unified output format. The pitch is narrow and practical: whatever arrives, the caller receives the same shape. Content is represented as a tree that stores headings and lists of any level, and alongside it the system extracts text formatting and metadata. That uniformity is the whole point. A team that has to accept statements of work, legal documents, technical reports and scientific papers, in whatever format each client sends, otherwise ends up writing and maintaining a branch per format. The project documentation describes dedoc as integrable into a document content and structure analysis system as a separate module, and it is implemented in Python with support for semi-structured formats such as DOC, DOCX, ODT, XLS, XLSX, CSV, TXT and JSON, plus unstructured inputs including images, archives, PDF and HTML. Structure extraction is described as fully automatic regardless of the input data type, which is a strong claim that the format specific handlers below are what make plausible.

Office documents are read through their internal representation

How a format is handled differs by family, and the documentation is specific about the office group. DOCX, XLSX and PPTX, plus formats convertible to them, are handled by analysis of the format inner representation using specialised libraries, and those libraries are named: python-docx and BeautifulSoup as the specialised libraries for the office group. The HTML, EML and MHTML group is parsed by tag analysis, and the HTML handler is reused for the other two formats in that group, so a single handler covers all three. TXT is treated differently from everything else, since only the raw textual content is analysed with no structure model at all. Archives are handled by analysing the attachments inside them, which means an archive is not a wrapper you unwrap yourself but an input whose contents are parsed as documents. This split matters when you set expectations: a TXT file will never produce a heading tree, and a DOCX will produce a much richer structure than a PDF of the same text, because the PDF path has to reconstruct formatting that the office format records explicitly.

PDF text layers and table borders are separate hard problems

Two PDF specific capabilities stand out. The first is that dedoc determines automatically whether the textual layer of a PDF is correct, which is a sanity check many pipelines skip and then debug for hours. The second is that content and formatting are extracted from PDF documents with a textual layer using an interpreter of a virtual stack machine for printing graphics, developed according to the format specification. That is an unusual phrase for a project description, and it points to reimplementing the page description interpreter rather than calling a viewer. Tables are handled separately again. The documentation describes recognising the physical structure and the cell text of complex multipage tables with explicit borders using contour analysis, and the supported sources for table data are DOC, DOCX, PDF, HTML, CSV and image formats. Contour analysis on explicit borders means a table without visible ruling is a case where the stated mechanism does not apply, so any assumption that all tables come out cleanly should be tested against your own documents before you build on top of it.

Scanned pages are the slow branch, handled by Tesseract plus machine learning

Scanned documents, meaning image formats and PDFs without a text layer, are covered by combining Tesseract with image preprocessing methods. On top of OCR the system applies machine learning approaches to detect document orientation, to detect whether a page is single or multicolumn, to detect bold text, and to extract a hierarchical structure from features extracted from the document images. In other words the reading order and the hierarchy are inferred rather than read, and that inference is the expensive part. The dependency list backs this up: opencv-python, scikit-image, scikit_learn, xgboost and xgbfir sit alongside pytesseract, and the packaging metadata offers a separate torch extra that pulls in torch, torchvision and transformers for the deep learning components. A consequence for deployment is that the plain installation and the machine learning installation are not the same thing, and the OCR branch will dominate latency on scanned input. If your input is born digital, this whole branch never runs.

Running dedoc as a service with the compose file in the repository

The repository ships a Dockerfile, a docker-compose.yml and a separate docker_gpu/ directory, and the compose file defines three services: dedoc itself, a test service that depends on both dedoc and grobid, and a grobid service using the grobid/grobid:0.8.2 image. The dedoc service is where the interesting configuration lives:

  dedoc:
    mem_limit: 16G
    build:
      context: .
    restart: always
    tty: true
    ports:
      - 1231:1231
    environment:
      DOCREADER_PORT: 1231
      GROBID_HOST: "grobid"
      GROBID_PORT: 8070

Two things jump out. The memory limit is set to 16G, which is a strong hint about how heavy the processing can get, and the container is told where to find grobid by host and port rather than by a URL. The grobid service it points at is configured like this:

  grobid:
      image: "grobid/grobid:0.8.2"
      ports:
        - 8070:8070

The compose file exposes dedoc on port 1231 through the DOCREADER_PORT variable, and the requirement list shows why a server shape is possible at all: fastapi, starlette and uvicorn are all pinned in the dependencies, alongside python-multipart for uploads. Images are published under the dedocproject/dedoc name on Docker Hub, and a demo instance is hosted as a Hugging Face space, which gives you something to point a client at before you build anything. Running the stack locally means building the dedoc image from the repository root, since the build context is the current directory.

The dependency set is wide and several packages are pinned hard

The requirements file shows what the project actually leans on, and it is a long one. PDF work alone brings pypdf, pypdfium2, pdfminer.six and pdf.tocgen for table of contents generation, plus pdf2image for rasterising. Office formats bring python-docx, xlrd for the older spreadsheet format, olefile and py7zr for archives, and rarfile for RAR. The puremagic and python-magic entries carry a comment that libmagic must be installed in the system, which is an easy thing to miss when deploying to a slim container. Several packages carry narrow version ceilings rather than open ranges: scipy is limited to <=1.11.2, scikit-image to <=0.21.0, scikit_learn to <=1.2.2, opencv-python to <4.6.0 and pdf2image is pinned to exactly 1.10.0 with a comment about conversion artifacts in a later version. Open version ceilings are a maintenance constraint, not a style choice. Compare that with the alternative approach, which is to assemble your own chain out of the same underlying libraries such as pdfminer.six, pytesseract and opencv-python and write the format dispatch yourself. That gives you full control over behaviour and dependency versions, and it costs you the automatic structure detection and the unified tree that dedoc exists to provide.

Apache-2.0, a steady release line, and a Python version gap

The licence is Apache-2.0, with the full text kept in LICENSE.txt and the packaging metadata pointing at that file. It is a permissive licence with an explicit patent grant, and the practical requirement is to keep the notice and licence text with any redistribution. The project also shipped support work funded by a 2022 grant from the Innovation Assistance Foundation, which is worth knowing because it explains the depth of the format coverage. On versions, the release line moves steadily: v2.6.1 on 2025-12-16, v2.7 on 2026-06-25 and v2.8 on 2026-09-22, with the last push to the repository landing on 2026-09-29, so the work is current rather than abandoned. One detail to check before you build a deployment on it: the packaging metadata sets requires-python to >=3.8 while the classifiers only list Python 3.8, 3.9 and 3.10, so newer interpreters are not declared as supported even though the floor permits them. The version number itself is read from a VERSION file and written into a generated version module at build time, which is why the metadata declares version as dynamic.

Editorial conclusion

Adopt dedoc when your pipeline must accept whatever a customer uploads and still emit one predictable structure, especially if scanned PDFs and multipage tables are part of that mix, and run it as the container described in docker-compose.yml so GROBID is reachable at GROBID_HOST and GROBID_PORT. Do not choose it if you only need to read one well formed format, since a targeted parser is simpler, and expect the OCR path to be the slowest and least predictable branch. Before committing, check that version 2.8, released on 2026-09-22, covers the formats you need, confirm that your Python version sits inside the >=3.8 requirement, and verify that the machine you deploy on can hold the 16G memory limit the compose file declares.

Frequently asked questions

Official sources

1. ispras/dedoc on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases