PyTeXMK

LaTeX 辅助编译命令行程序

简体中文 · English

✨ 功能特性

🚀 多引擎支持：XeLaTeX、PdfLaTeX、LuaLaTeX 三大编译引擎
📚 参考文献：支持 bibtex、biblatex、thebibliography
📑 索引支持：glossaries（含 glossaries-extra + bib2gls + biber）、nomencl、makeidx
📋 结构化编译检测报告：将 6 维检测状态（参考文献/索引/目录/交叉引用/书签文件/日志 Rerun）与本轮结论整合为统一报告区块；报告采用 Rich 5 色分层彩色（标题洋红、名称青粗、[OK]绿粗、[!!]黄粗、安全上限红粗）+ 粗体，禁用表格网格，纯条目列表输出；[OK] 状态不再千篇一律「状态稳定」，改为 6 维度各自独立的动态稳定文案（如「参考文献引用计数无变化，参考文献解析稳定」「PDF 书签条目未发生变更，书签生成稳定」等）；结论行 actual_next 语义严格对齐（2→1→无需，绝不兜底为 1，绝不打印「需额外进行 0 次」），编译名称按实际引擎动态替换为 XeLaTeX/PdfLaTeX/LuaLaTeX；所有报告文案完整适配国际化 _() 包装
🔁 智能多次编译检测：自动比较 aux/out 文件内容并解析日志 Rerun 警告，确保交叉引用、hyperref 书签、lastpage 总页数等收敛稳定
🔮 魔法注释：通过 % !TEX 注释指定编译引擎、主文件、输出目录等；正则已加固，行内 TeX 转义百分号 \% 不会被误识别为魔法注释起始
🌍 国际化：支持多语言界面；默认界面语言为中文（源码字符串即中文），不强制默认英文；v1.2.1 起全面采用 pybabel 官方工作流（pybabel extract → init → update → compile），不再使用 xgettext / msgfmt；所有用户可见文案 100% _() 包装 + %(name)s 占位；3 组遗留共享域全部拆为独立域（lifecycle / paths、pdf_tools / subprocess_runner / tex_project、timing / ui_messages），与 set_language 参数、locale 文件名 1:1 严格对齐；提供新增语言的交互式命令（make lang-add 终端提问语言代码）、自动更新所有 pot/po 的 make lang-update、把 po 编译成 mo 的 make lang-mo、以及重抽所有 pot 的 make lang-poup
🧹 智能清理：支持多种清理模式，精确清理辅助文件
🔍 日志解析：编译失败后自动解析 LaTeX 日志，定位错误
📝 LaTeXDiff：支持 LaTeX 文件差异对比
⚙️ 配置文件：支持用户配置和项目配置两级配置
🔔 版本检查：自动检查更新，第一时间获取新版本
🪓 检测与编译彻底解耦（零薄转发）：新建独立 detection.py 模块承载全部 6 维检测逻辑与 CompilationDetector 类，compile.py 仅保留 subprocess 级编译执行；强制采用组合关系调用（compile_model.detector.*），严禁任何薄转发方法（return self.detector.xxx(...) = 0），单一职责与可维护性拉满
🧱 分层架构 + DAG 无环 import：基于 23 模块静态拓扑调查的「凝聚度硬阈值」拆分出唯一达标的 cli/ 子包（__main__ / cli_args / cli_workflow / check_version），其余 19 模块保持扁平避免过度工程；同时打破 run ↔ cli_workflow 静态 2 节点 SCC 环，import 图正式 DAG 化（SCC≥2 分量 = 0），从结构上消除循环依赖隐患
🪧 预处理 Banner + 预处理日志差异化：预处理控制台 Banner 回归复古三行 =*78 / X32|开始预处理|X32 / =*78 风格，与项目其他 Banner 统一走 ui_messages.print_message；删除「结束预处理」横幅；预处理段按「move 0/N 个辅助文件」「exist 0/N 个已有辅助文件」4 场景差异化打印提示，避免无论是否实际迁移都两行固定输出的歧义；「未检测到已有辅助文件，进行初始化」文案全局只保留 1 处，归属 cli_workflow
🚫 零兼容承诺 + 冗余清理 + 永久去 Cython 加密：v1.2.1 起不保留任何兼容层（彻底删除旧 pytexmk.run 入口 / DeprecationWarning / try-import fallback）；永久移除 Cython 加密打包链路（删除 tools/pydmk.py、srcpyd/ 入口、cython 依赖、三平台 GA 编译工具链安装步骤），打包流程永久只有「源码模式 onedir」一条路径；核心模块持续执行 ruff F401/F841 + 死注释清理，控制架构熵增速率
🗺 架构决策制度化：新增 docs/architecture.md 作为单一事实源，给出 6 层 ASCII 分层依赖图、23 模块职责矩阵、新功能放哪的 Q1~Q4 决策树 + 规则 5「子包拆分硬阈值（≥4 模块 AND ≥3 内引 AND ≥0.7 耦合系数）」、以及 3 条 import 纪律，约束架构熵增速率

📸 预览

🚀 快速开始

安装

官方版本 PyTeXMK 发布在 PyPI 上，可以通过 pip 或 uv 轻松安装：

# 使用 pip 安装
pip install pytexmk

# 使用 uv 安装（推荐）
uv pip install pytexmk

Windows winget 安装（推荐）

Windows 10 1809+ / Windows 11 用户可使用 winget 一键安装（无需 Python 环境）：

winget install --id YanMing-lxb.PyTeXMK

提示：若已完成 moniker 注册，可简写为 winget install pytexmk。

升级

# pip
pip install --upgrade pytexmk

# uv
uv pip install --upgrade pytexmk

基本使用

在 LaTeX 项目根目录下运行：

# 使用默认配置编译
pytexmk

# 指定主文件编译
pytexmk main.tex

# 使用 XeLaTeX 编译
pytexmk -x main.tex

# 清理辅助文件
pytexmk -c

注意：PyTeXMK 仅支持 UTF-8 编码的 TeX 文件。

⚙️ 默认配置

配置项	默认值	说明
编译程序	`XeLaTeX`	可选：XeLaTeX、PdfLaTeX、LuaLaTeX
主文件名	`main.tex`	待编译的 LaTeX 主文件
输出目录	`Build`	编译结果存放目录
辅助目录	`Auxiliary`	辅助文件存放目录
编译模式	batch 模式	编译过程不显示详细信息

提示：以上参数均可在配置文件中修改，详见配置文件说明。

VSCode 用户需在 settings.json 中设置 "latex-workshop.latex.outDir": "./Build" 以便 LaTeX-Workshop 找到 PDF 文件。

📖 使用说明

编译命令

PyTeXMK 支持的编译选项：

位置参数

参数	说明
`document`	要被编译的文件名

选项参数

选项	说明
`-h`, `--help`	显示帮助信息
`-v`, `--version`	显示程序版本号
`-p`, `--PdfLaTeX`	使用 PdfLaTeX 进行编译
`-x`, `--XeLaTeX`	使用 XeLaTeX 进行编译
`-l`, `--LuaLaTeX`	使用 LuaLaTeX 进行编译
`-d`, `--LaTeXDiff`	使用 LaTeXDiff 生成改动对比文件
`-dc`, `--LaTexDiff-compile`	使用 LaTeXDiff 生成对比文件并编译新文件
`-dr`, `--draft`	启用草稿模式（无图显示，提高编译速度）
`-c`, `--clean`	清除主文件的辅助文件
`-C`, `--Clean`	清除辅助文件（含根目录）和输出文件
`-ca`, `--clean-any`	清除所有带辅助文件后缀的文件
`-Ca`, `--Clean-any`	清除所有辅助文件（含根目录）和主文件输出
`-nq`, `--non_quiet`	非安静模式，显示编译过程
`-vb`, `--verbose`	显示 PyTeXMK 运行详细信息
`-pr`, `--pdf-repair`	修复所有根目录以外的 PDF 文件
`-pv`, `--pdf-preview`	编译后预览 PDF 文件
`-s`, `--subproject`	从根配置 `[subprojects]` 中选中子项目并在其目录编译
`-ls`, `--list-subprojects`	扫描子项目并展示清单（自动同步根配置 `[subprojects]` 段）
`-i`, `--init`	生成根项目 `.pytexmkrc` 配置文件
`-iu`, `--init-user`	生成用户级 `~/.pytexmkrc` 配置文件
`-f`, `--force`	配合 `-i`/`-iu` 强制覆盖已存在的配置文件

参数说明

-pr：当 LaTeX 编译过程中报类似 invalid X X R object at offset XXXXX 的警告时，可使用此参数尝试修复所有 PDF 文件。该警告通常由 PDF 图片文件损坏导致。
-d / -dc：输入示例：pytexmk -d old_tex_file new_tex_file，生成的改动对比文件名为 LaTeXDiff.tex。
-pv：编译结束后调用浏览器或本地 PDF 阅读器预览。示例：pytexmk main -pv 或 pytexmk -pv。
-dc / -d：支持在参考文献和符号索引中显示修改痕迹，编译过程中会提示选择风格（1-显示修改 / 2-不显示修改）。

多子项目编译

PyTeXMK 支持在一个项目根目录下管理并逐一编译多个相互独立的子项目。

-s / -ls / -i / -iu / -f 相关说明：

选项	说明
`-s`, `--subproject <名称>`	从根 `.pytexmkrc` 的 `[subprojects]` 段选中一个子项目，并在其目录下编译/清理；进程内部切换工作根，不改变用户终端 cwd，可与主文件名共存（如 `pytexmk -s 子项目 main`）；alias 未命中时报错并提示先运行 `-ls`，以「项目不存在」退出码退出
`-ls`, `--list-subprojects`	按根配置 `[project_scan]` 规则扫描并表格展示子项目清单；若根 `.pytexmkrc` 存在，会把 `[subprojects]` 段整体替换为扫描结果（结果幂等），`[project_scan]` 段不被改动；若 rc 不存在则提示先运行 `-i`、不写盘
`-i`, `--init`	生成根项目 `.pytexmkrc` 配置文件
`-iu`, `--init-user`	生成用户级 `~/.pytexmkrc` 配置文件
`-f`, `--force`	仅配合 `-i`/`-iu` 覆盖已存在文件；目标已存在且未加 `-f` 时提示且不写入

典型流程

在根目录执行 pytexmk -i 生成根配置 .pytexmkrc（需覆盖已有配置时加 -f）；需要全局配置时用 -iu 生成用户级 ~/.pytexmkrc
执行 pytexmk -ls 扫描并展示子项目清单（自动把根配置的 [subprojects] 段更新为扫描结果）
用 pytexmk -s 子项目名 选中子项目并编译，也可与主文件名共存：pytexmk -s 子项目名 main；清理作用域同样生效，如 pytexmk -s 子项目名 -c

配置说明

[project_scan]：子项目扫描规则段（默认 depth=3、exclude 排除清单）。仅用于 -ls/-s 扫描，扫描参数统一取根配置；-ls 与 -s 均不会覆盖或修改该段内容
[subprojects]：子项目清单段，由 -s 选中使用；-ls 会将其整体替换为扫描结果

本地 rc 作用域

从根目录用 -s 调用时，会忽略子项目目录下的本地 .pytexmkrc（-vb 会打印一行提示），以根配置为绝对来源
用户 cd 进入子项目目录独立运行时，本地 rc 生效（向后兼容）

魔法注释

PyTeXMK 支持使用魔法注释来自定义编译行为（仅检索文档前 50 行）。

魔法注释	说明	示例
`% !TEX program = <XeLaTeX>`	指定编译类型	`% !TEX program = PdfLaTeX`
`% !TEX root = <主文件名>`	指定待编译主文件	`% !TEX root = test_file`
`% !TEX outdir = <输出目录>`	指定编译结果存放位置	`% !TEX outdir = output`
`% !TEX auxdir = <辅助目录>`	指定辅助文件存放位置	`% !TEX auxdir = auxfiles`

注意：魔法注释仅支持在主文件中定义，不支持在子文件中定义。

主文件与编译类型选定逻辑

📂 待编译主文件选定逻辑

命令行参数中指定主文件 → 编译该文件（如 pytexmk <主文件名>，可省略后缀）
当前目录仅有一个 .tex 文件 → 默认使用该文件
存在魔法注释 % !TEX root → 使用注释指定的文件
检索 \documentclass[]{} 或 \begin{document} 判定（仅前 200 行）
默认主文件名 main.tex → 尝试使用
以上均失败 → 输出错误信息并退出

⚙️ 编译类型选定逻辑

命令行参数 -p / -x / -l 指定 → 优先级最高
魔法注释 % !TEX program 指定 → 使用注释值
均未指定 → 使用默认 XeLaTeX

输出目录优先级：% !TEX outdir 魔法注释 > 默认 Build

配置文件说明

PyTeXMK 支持两级配置文件：用户级配置和项目级配置。正常运行不再自动生成配置文件，需要时用 -iu（用户级）或 -i（项目级）手动生成。

用户级配置：pytexmk -iu 手动生成，位于用户主目录下 .pytexmkrc
项目级配置：pytexmk -i 手动生成，位于当前工作目录下 .pytexmkrc

生成的配置文件中包含详细注释，可根据需要进行修改。

配置文件路径

类型	Windows	Linux / macOS
系统配置	`C:\Users\用户名\.pytexmkrc`	`~/.pytexmkrc`
项目配置	当前目录 `.pytexmkrc`	当前目录 `.pytexmkrc`

优先级：项目级配置 > 用户级配置 > 内置默认；缺失配置用内置默认静默运行，键不匹配仅警告、不写盘。

🛠 开发与构建

环境要求

Python 3.14+
uv（推荐）或 pip

开发环境搭建

# 克隆项目
git clone https://github.com/YanMing-lxb/PyTeXMK.git
cd PyTeXMK

# 安装开发依赖
uv sync --all-extras --dev

# 运行开发版本
uv run pytexmk --help

构建分发包

# 构建 wheel 和 sdist
uv build

构建可执行程序

# 生成平台图标
make icon

# 构建源码模式的可执行程序（onedir 目录）
make build

# 清理构建产物
make clean

Windows 中的 make 命令需要单独配置，详见 Windows 下使用 make。

代码检查

uv run ruff check src/
uv run ruff format src/

📄 许可证

本项目基于 GPLv3 许可证开源。

📝 更新记录

详细更新记录请参阅 CHANGELOG.md。

⭐ Star History

如果这个项目对你有帮助，欢迎点个 Star ⭐ 支持一下！

Environment
- Console
Intended Audience
Operating System
- OS Independent
Programming Language
- Python :: 3.14

Release files for pytexmk 1.2.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pytexmk 1.2.6
File	Size	Uploaded
pytexmk-1.2.6.tar.gz	114.1 kB	Sep 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pytexmk 1.2.6
File	Interpreter	ABI	Platform	Reset
pytexmk-1.2.6-py3-none-any.whl 144.8 kB Sep 25, 2026	Python 3	none	any	Details

Total release size: 258.8 kB

Release files / pytexmk-1.2.6.tar.gz

Download URL	pytexmk-1.2.6.tar.gz
Size	114.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`224b889820ca0289cecae431bf92f31c62495b7173b28e4a10368a3044952052`
BLAKE2b-256 checksum How to use checksums	`e95507c04d58230fab0bcdc2ed69f002251c9df76c6ddf439622aa7caf1225b9`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/YanMing-lxb/PyTeXMK
Publishing commit: github.com/YanMing-lxb/PyTeXMK/tree/e52aaa687fbc80fdbb21ce2ad14bd95e6011d2ae

Workflow

Publishing configuration: github.com/YanMing-lxb/PyTeXMK/blob/e52aaa687fbc80fdbb21ce2ad14bd95e6011d2ae/.github/workflows/Release.yml
Publishing logs: github.com/YanMing-lxb/PyTeXMK/actions/runs/36143701254/attempts/1

Artifact

Subject: pytexmk-1.2.6.tar.gz
SHA-256 checksum: 224b889820ca0289cecae431bf92f31c62495b7173b28e4a10368a3044952052 Verifying attestations

Release files / pytexmk-1.2.6-py3-none-any.whl

Download URL	pytexmk-1.2.6-py3-none-any.whl
Size	144.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7d94dcf6326e2529a5a3819ca72ce388566080e7c1af7e0fba2ca49ce7f27cd4`
BLAKE2b-256 checksum How to use checksums	`7725cd025c74578739af03e28199df427b323e0abc2becd8762298ffdd157564`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/YanMing-lxb/PyTeXMK
Publishing commit: github.com/YanMing-lxb/PyTeXMK/tree/e52aaa687fbc80fdbb21ce2ad14bd95e6011d2ae

Workflow

Publishing configuration: github.com/YanMing-lxb/PyTeXMK/blob/e52aaa687fbc80fdbb21ce2ad14bd95e6011d2ae/.github/workflows/Release.yml
Publishing logs: github.com/YanMing-lxb/PyTeXMK/actions/runs/36143701254/attempts/1

Artifact

Subject: pytexmk-1.2.6-py3-none-any.whl
SHA-256 checksum: 7d94dcf6326e2529a5a3819ca72ce388566080e7c1af7e0fba2ca49ce7f27cd4 Verifying attestations