PDFMathTranslate: 1.x here, 2.0 in another repo

The 1.x line lives here and 2.0 lives in a second repository

Get the line straight before anything else. The project page carries a note saying version 2.0 moved to a new repository under the same organisation, PDFMathTranslate/PDFMathTranslate-next, and that the 2.0 official release has been published there. A preview of 2.0 was announced for 2025-05-09 with a Windows ZIP and a Docker image. So this repository is the 1.x line, and it is not frozen. The last push was on 2026-09-29 and the updates list has entries for 2026-09-08 and for several days in March 2026, including experimental OCR support and experimental support for the v2.0 translation kernel through `--mode precise`. The version numbering is also loose: the newest GitHub release is v1.9.11 from 2025-07-11 while `pyproject.toml` declares version 1.9.12, and the package description there is still the older string Latex PDF Translator.

Two installs, and the supported Python range is two versions wide

The command line route comes in two flavours with the same result. With uv:

pip install uv
uv tool install --python 3.12 pdf2zh

Or straight from PyPI:

pip install pdf2zh

Both instructions open by requiring Python with a version of 3.11 or above and 3.12 or below, and `pyproject.toml` agrees, setting `requires-python` to `>=3.11,<3.13`. That upper bound is the first constraint to plan around. A machine whose system interpreter is 3.13 is outside the declared range, and the fix is an interpreter you install rather than a flag. The class list also declares the package operating system independent, so the same wheel is meant to serve every platform, with one carve-out noted in the dependency list for arm64 Linux. Running it is one argument, and output lands in the current working directory:

pdf2zh document.pdf

The interface is a web server on 7860, not a desktop window

There is no separate GUI package. You install the same `pdf2zh` and add one flag:

pdf2zh -i

That starts an interactive interface in a browser, and if the browser does not open on its own the page is at `http://localhost:7860/`. This matters more than it first appears, because the container image does exactly the same thing. The compose file sets `command: ["pdf2zh", "-i"]` and publishes 7860, and the Dockerfile carries the same `CMD`. So a deployed container is a web interface on a port, not a headless translator you can drive from a queue. If you are wiring this into a pipeline, the flag-free form is the one that writes files and exits, and anything exposing 7860 is exposing an interface meant to be looked at by a person. The Windows route is different again: download `pdf2zh-version-win64.zip` from the release page and run `pdf2zh.exe`, and the project documents a specific failure where the file will not open until `vc_redist.x64.exe` is installed.

Optional extras decide which runtimes you actually pull in

The base dependency list is not small. It already carries `onnxruntime`, `opencv-python-headless`, `gradio` and `pikepdf`, so the CPU path is in the default install. Everything else is an extra, and the names tell you what each one is for. The `ocr` extra adds `pooch`, which the comment marks as being for the first-use downloads behind PyMuPDF's built-in OCR. `backend` adds flask, celery and redis, which is the asynchronous server path. `argostranslate` adds a local translation engine. `mcp` adds the Model Context Protocol server at 1.6.0 or newer. `cuda` swaps in `onnxruntime-gpu` and `dml` swaps in `onnxruntime-directml`, so hardware acceleration is opt-in. The odd one is `precise`, which installs nothing at all. It is a marker, and the comment says to run `pdf2zh-setup-precise` after install to provision an isolated virtual environment for the 2.0 kernel.

Four dependencies are pinned below their latest, each for a stated reason

The pins in `pyproject.toml` are load-bearing, and the file says why for three of them. `pymupdf` is held below 1.25.3 with a comment about arm64 Linux wheels. `gradio` is held below 5.36 because 5.36 has a bug that starts the web interface with a white screen. `tencentcloud-sdk-python-tmt` is fixed at exactly 3.1.70 because newer releases remove the TextTranslate API the tool calls. `pdfminer-six` is fixed at 20250416, `babeldoc` sits in a narrow band above 0.1.22 and below 0.3.0, and the Azure translation client is capped at 1.0.1. Read those as maintenance obligations rather than as taste. When a pinned release stops installing on your interpreter or your platform, the failure arrives at install time with a resolver error rather than at run time, and the comment beside the pin tells you which constraint to relax first. The two newest features are also the two flagged experimental ones, OCR support as of 2026-09-08 and the precise kernel mode as of 2026-03-23.

The container build exists to fix libGL.so.1, and it warms babeldoc at build time

Read the compose file and the reason for its shape is in the comments. It builds a single self-contained image from `ghcr.io/astral-sh/uv:python3.12-bookworm-slim`, and the first step installs system libraries, with a comment saying this is what solves the libGL.so.1 not found error:

apt-get install --no-install-recommends -y libgl1 libglib2.0-0 libxext6 libsm6 libxrender1 libreoffice-core libreoffice-writer

The standalone Dockerfile installs the same set plus `libreoffice-core` and `libreoffice-writer`, then runs `babeldoc --warmup` after installing the package and again after re-pinning `babeldoc<0.3.0`, `pymupdf<1.25.3` and `pdfminer-six==20250416`. So the image performs real work at build time that a local `pip install` does not, which is why the first container run is faster than the first local run. The cost is an image that is not a thin wrapper and a build that touches the network twice. If Docker Hub is unreachable, the project gives a second pair of commands pointing at GitHub Container Registry instead: `docker pull ghcr.io/byaidu/pdfmathtranslate` followed by the same `docker run -d -p 7860:7860`.

A model is fetched on first run, and that is where installs appear to break

The documented failure mode is a download, not a bug. The project says the program relies on an AI model named `wybxc/DocLayout-YOLO-DocStructBench-onnx`, that some users cannot download it because of network restrictions, and that setting an `HF_ENDPOINT` environment variable works around it. That single dependency shapes the whole install story, because it means the tool is not offline after `pip install`. A first run on a restricted network fails in a way that looks like a broken install, and the online demos at `pdf2zh.com` on HuggingFace and on ModelScope exist partly so people can try before committing to that. There is a free public service at `pdf2zh.com` that needs no installation, plus a BabelDOC route through Immersive Translate with a free quota, and the project asks users not to abuse the demos because the compute is limited. The Zotero integration is a third-party plugin in a separate repository, guaguastandup/zotero-pdf2zh, and the release notes still link downloads under the older Byaidu organisation path.

Editorial conclusion

Use PDFMathTranslate when the document is a paper with formulas you cannot afford to have reflowed, and pick a delivery route deliberately: the CLI for scripts, the browser interface when a person reviews output, the container when your network blocks model downloads. Do not start from 2.0 tutorials in this repository, because the project's own note puts 2.0 in PDFMathTranslate/PDFMathTranslate-next. Before installing, check the dependency caps in pyproject.toml, because pymupdf, gradio, tencentcloud-sdk-python-tmt and babeldoc are all held below or at a fixed version for stated reasons.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes