PDFMathTranslate

Special thanks to: Warp, built for coding with multiple AI agents Available for macOS, Linux and Windows

English | 简体中文 | 繁體中文 | 日本語 | 한국어

PDFMathTranslate

1. What does this do?

Scientific PDF document translation preserving layouts.

• 📊 Preserve formulas, charts, table of contents, and annotations.

• 🌐 Support multiple languages, and diverse translation services.

• 🤖 Provides commandline tool, interactive user interface, and Docker

2. Recent Updates

• [October 3, 2026] Translated PDFs automatically add spaces between adjacent CJK and Latin letters, including accented letters, in normal and --ultrafast modes.

• [October 2, 2026] Added the --ultrafast CLI mode for native-text PDFs. It uses pdf-inspector text positions for heuristic layout and skips ONNX layout and OCR. (by @reycn)

• [September 8, 2026] Experimental OCR support, with paragraph regrouping and adaptive typesetting. (by @reycn)

• [March 23, 2026] Experimental support for v2.0 translation kernel using isolated environment (--mode precise). (by @reycn)

• [March 22, 2026] Supporting MiniMax (PR by @octo-patch)

• [March 22, 2026] Fixing OpenAI-related issues (PR by @samqin123)

• [March 22, 2026] Fixing HTTP-related issues (PR by @soukouki)

• [March 22, 2026] Faster model loading on mac and OONX platforms, GUI starting-up, version printing, and continuous integration.(by @reycn)

• [May 9, 2025] pdf2zh 2.0 Preview Version #586: The Windows ZIP file and Docker image are now available.

  Note

  2.0 Moved to a new repository under the organization: PDFMathTranslate/PDFMathTranslate-next

  Version 2.0 official release has been published.

3. Use 🌟 3.1 Online Service 🌟

You can try our application out using either of the following demos:

• Public free service online without installation (recommended).

• Immersive Translate - BabelDOC Free usage quota is available; please refer to the FAQ section on the page for details. (recommended)

• Demo hosted on HuggingFace

• Demo hosted on ModelScope without installation.

Note that the computing resources of the demo are limited, so please avoid abusing them.

3.2 Local Installation

For different use cases, we provide distinct methods to use our program:

3.2.1 Python: Install using uv

1. Python installed (3.11 <= version <= 3.12)

2. Install our package:

   pip install uv
   uv tool install --python 3.12 pdf2zh

3. Execute translation, files generated in current working directory:

   pdf2zh document.pdf

3.2.2 Python: Install using pip

1. Python installed (3.11 <= version <= 3.12)

2. Install our package:

   pip install pdf2zh

3. Execute translation, files generated in current working directory:

   pdf2zh document.pdf

3.3.3 Python: Graphic user interface

1. Python installed (3.11 <= version <= 3.12)

2. Install our package:

   pip install pdf2zh

3. Start using in browser:

   pdf2zh -i

4. If your browser has not been started automatically, goto

   http://localhost:7860/

See documentation for GUI for more details.

3.2.4 Application: On Windows

1. Download pdf2zh-version-win64.zip from release page

2. Unzip and double-click pdf2zh.exe to run.

Tip

• If you're using Windows and cannot open the file after downloading, please install vc_redist.x64.exe and try again.

3.2.5 Reference manager: Zotero Plugin

See Zotero PDF2zh for more details.

3.2.6 Docker: Containerized Deployment

1. Pull and run:

   docker pull byaidu/pdf2zh
   docker run -d -p 7860:7860 byaidu/pdf2zh

2. Open in browser:

   http://localhost:7860/

For docker deployment on cloud service:

Tip

• If you cannot access Docker Hub, please try the image on GitHub Container Registry.

docker pull ghcr.io/byaidu/pdfmathtranslate
docker run -d -p 7860:7860 ghcr.io/byaidu/pdfmathtranslate

3.2.* Solutions for network issues in installation

Users in specific regions may encounter network difficulties when loading the AI model. The current program relies on the AI model (wybxc/DocLayout-YOLO-DocStructBench-onnx), and some users are unable to download it due to these network issues.

To address issues with downloading this model, use the following environment variable as a workaround:

  set HF_ENDPOINT=https://hf-mirror.com

For PowerShell user:

  $env:HF_ENDPOINT = https://hf-mirror.com

If the solution does not work to you / you encountered other issues, please refer to Frequently Asked Questions.

4. Technical Details

Experimental automatic OCR (fast mode)

Fast mode automatically runs local OCR on selected image-only pages before translation. Native text, existing OCR layers, and blank pages are skipped; the original pages in dual output remain unchanged. Install with pip install 'pdf2zh[ocr]' (or pip install -e '.[ocr]' from this checkout). The first scanned page downloads the requested language data from Tesseract's tessdata_fast 4.1.0 release into ~/.cache/pdf2zh/tessdata/4.1.0; subsequent