kogo
Layout-aware PDF diff for revisions — compare an old and new PDF and highlight added or deleted text, figures, and annotations, in the browser and in marked PDFs.
kogo (校合) is the Japanese publishing term for checking a revision against the original.
Website: https://kogo.tatu-sec.dev/ Documentation: https://kogo.tatu-sec.dev/manual/
Features
- Word-level text diff for Latin text, character-level precision for CJK (Chinese, Japanese, Korean) text, including rare kanji across CJK Extensions B-J
- Reading order reconstructed from whitespace layout, so multi-column pages and slide-style text boxes are compared correctly instead of interleaved
- Page alignment that tolerates inserted or removed pages, using both text and visual page signatures
- Visual diff for figures, equations, and layout, with text areas masked out and scanner/export shift registration for image-only pages
- Detects added or removed highlights, comments, and ink annotations
- Detects style-only changes (bold, italic, font-size) on otherwise-unchanged text, marked in amber
- Markers are baked into the output PDFs so they show up in any viewer, even with annotations hidden
- Selectable-text web preview powered by Mozilla PDF.js
- Downloadable old-highlighted, new-highlighted, and side-by-side comparison PDFs
- All processing happens locally — nothing is sent to an external service
Quick start
CLI only
pip install kogo
kogo diff old.pdf new.pdf -o out/
Web app
pip install "kogo[serve]"
kogo fetch-viewer
kogo serve
kogo fetch-viewer downloads the local PDF.js viewer assets used by the web preview (see Configuration); it's not needed with Docker, which bundles them in the image.
Then open http://127.0.0.1:8080.
Docker
docker compose up -d --build
Then open http://localhost:8080. By default the container only binds to 127.0.0.1 (localhost). To share it on a LAN, there is no authentication built in, so only do this on a trusted network:
KOGO_HOST=0.0.0.0 docker compose up -d --build
docker-compose.yml sets mem_limit: 2g, cpus: 2, and pids_limit: 256 as a backstop, since PyMuPDF and OpenCV are native-code parsers processing untrusted PDFs. Raise these if legitimate large comparisons get OOM-killed or throttled. Equivalent docker run flags: --memory=2g --cpus=2 --pids-limit=256.
CLI usage
kogo diff OLD.pdf NEW.pdf \
-o kogo-diff \
--dpi 144 \
--sensitivity standard \
--max-pages 200
Options:
-o, --out— output directory (defaultkogo-diff)--dpi— rendering resolution for the visual diff, 96–180 (default 144)--sensitivity—high,standard, orlow(defaultstandard)--max-pages— maximum pages per file (default 200)--no-previews— skip generating page preview images--json— print the full result as JSON
kogo serve runs the web application:
kogo serve --host 127.0.0.1 --port 8080
Use as a library
The diff engine is a regular Python API — pip install kogo is enough (no web dependencies needed):
import kogo
result = kogo.compare_pdfs("old.pdf", "new.pdf", "out/")
print(result["summary"])
# out/ now contains old-highlighted.pdf, new-highlighted.pdf,
# side-by-side.pdf, result.json, and page previews.
kogo.compare_pdfs raises kogo.ComparisonError for user-facing problems (encrypted, empty, oversized, or unreadable PDFs). Keyword options mirror the CLI: dpi, sensitivity, max_pages, previews, old_name, new_name.
Configuration
The web app reads these environment variables:
| Variable | Default | Description |
|---|---|---|
JOBS_DIR |
~/.local/share/kogo/jobs |
Where uploaded files and comparison results are stored |
MAX_UPLOAD_MB |
100 | Maximum size per uploaded PDF |
MAX_PAGES |
200 | Maximum pages per PDF |
JOB_TTL_HOURS |
24 | How long comparison results are kept before cleanup |
MAX_CONCURRENT_JOBS |
2 | Number of comparisons processed at once |
JOB_TIMEOUT_SECONDS |
900 | Wall-clock limit for a single comparison before it's aborted (minimum 60) |
KOGO_VENDOR_DIR |
~/.local/share/kogo/vendor/pdfjs |
Where kogo fetch-viewer installs (and the server looks for) the local PDF.js viewer assets |
KOGO_SOURCE_URL |
https://github.com/ta-061/kogo |
Source code link shown in the web app footer and the kogo serve startup banner — see License |
How it works
Text is extracted at word precision (character precision for CJK) and reordered using recursive whitespace cuts, so columns, slide text boxes, and reflowed paragraphs are read in a sensible order rather than the PDF's raw internal stream order. Pages are aligned across the two documents with a similarity-based sequence alignment (combining text and, for image-heavy pages, visual signatures) so inserted or removed pages don't desynchronize the rest of the comparison. Remaining differences are then diffed with Python's difflib.
Figures, equations, and other non-text layout are compared by rendering each page to an image, masking out the areas already covered by the text diff, and taking a pixel difference. Image-only pages get a small registration step to correct for scanner or export shifts before the pixel diff runs. Existing PDF annotations (highlights, comments, ink) are fingerprinted and diffed separately.
Limitations
- Scan-only PDFs (no embedded text layer) are compared visually; add an OCR text layer first if you need word-level text diffs
- Password-protected PDFs are not supported
- Complex tables and vertical text layouts may need a visual check in addition to the automated diff
- There is no authentication built in.
kogo serveand the default Docker Compose setup only bind to localhost; put the web app behind a reverse proxy with authentication before exposing it to anything beyond your local machine or trusted LAN MAX_UPLOAD_MBis enforced while reading each upload, but a client that sends a large body without aContent-Lengthheader (chunked transfer) is only caught by that same streaming check, not rejected up front; a reverse proxy in front of kogo should also set its own body-size limit (e.g. nginxclient_max_body_size) for defense in depth
Development
python -m unittest discover -s tests -v
License
kogo is licensed under AGPL-3.0. See LICENSE.
Copyright (C) 2026 ta-061. Released under the GNU Affero General Public License v3.0 (AGPL-3.0-only).
PyMuPDF (and the underlying MuPDF library) is distributed under AGPL-3.0-or-commercial; check its license terms before redistributing kogo or offering it as a network service.
If you modify kogo and let others use it over a network (for example, by self-hosting a modified version of the web app), AGPL-3.0 §13 requires you to offer those users the corresponding source code. The "Source code" link in the web app's footer and the kogo serve startup banner both read from the KOGO_SOURCE_URL environment variable (default: this repository) — operators running a modified build must set it to their own fork's repository to satisfy §13.
Credits:
- Mozilla PDF.js (Apache-2.0)
- PyMuPDF (AGPL-3.0-or-commercial)
- OpenCV (Apache-2.0)
- FastAPI (MIT)
Metadata
Release files for kogo 0.1.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kogo-0.1.7.tar.gz | 72.5 kB | With provenance | Details for kogo-0.1.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kogo-0.1.7-py3-none-any.whl | Python 3 | none | any | Details for kogo-0.1.7-py3-none-any.whl |
Total release size: 144.4 kB
Release files / kogo-0.1.7.tar.gz
| Download URL | kogo-0.1.7.tar.gz |
|---|---|
| Size | 72.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d370aa4fe2a39c6be32211e9cc38038a359da9c3cde696b08fee2016fdd6c73e
|
|
BLAKE2b-256 checksum How to use checksums |
3af4a79cd8525d0b97cac70429e337a0046f3fbec7dbf0ddb11fa16fba371f8d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 23, 2026.
Transparency logRelease files / kogo-0.1.7-py3-none-any.whl
| Download URL | kogo-0.1.7-py3-none-any.whl |
|---|---|
| Size | 71.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1044a392fd52d81c2583eb046251881ceb193a0851c714ab014966d1ce7f2b0a
|
|
BLAKE2b-256 checksum How to use checksums |
5a8ec869947145bc26776e6d1b71103d034f7551e4a16ede4081255908e94d44
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 23, 2026.
Transparency logSecurity for kogo 0.1.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for kogo-0.1.7.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 23, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.