PyTeXMK

LaTeX 辅助编译命令行工具

PyTeXMK（Python TeX Make）是一个用 Python 编写的 LaTeX 自动化编译工具，灵感来源于 latexmk。它能够根据辅助文件变化智能决定编译轮次，配合 Rich 彩色输出、参考文献/索引工具链自动调度，让 LaTeX 编译工作流一键完成。

✨ 功能特性

核心编译

🚀 多引擎支持：XeLaTeX、PdfLaTeX、LuaLaTeX，通过命令行参数或魔法注释灵活切换
🔁 智能多次编译检测：自动比较 .aux/.out 文件内容并解析日志 Rerun 警告，确保交叉引用、hyperref 书签、总页数等收敛稳定
📋 结构化编译检测报告：每轮编译结束后输出 6 维检测状态（参考文献、索引、目录、交叉引用、书签文件、日志重编译），清晰展示各维度是否稳定及预期下一步

参考文献与索引

📚 参考文献：自动调度 bibtex / biblatex（biber）/ thebibliography
📑 索引与术语表：glossaries（含 glossaries-extra + bib2gls + biber）、nomencl、makeidx，自动选择 xindy 或 makeindex 后端
🔮 魔法注释：通过 % !TEX 注释指定编译引擎、主文件、输出目录、辅助目录等

辅助工具

🧹 智能清理：多种清理模式，支持按目录范围和文件后缀精确清理辅助文件
🔍 日志解析：编译失败后自动解析 LaTeX 日志，定位错误位置
📝 LaTeXDiff：两个 LaTeX 文件差异对比，生成带修订标记的 PDF
🖼 PDF 修复与预览：损坏 PDF 自动修复，编译后自动预览

配置与扩展

🌍 国际化：支持多语言界面，默认中文
⚙️ 两级配置文件：用户级 + 项目级 .pytexmkrc，所有参数均可自定义
🧩 多子项目管理：一个根目录下管理多个独立子项目，支持自动扫描和逐一编译
🪲 版本检查：自动检查更新，第一时间获取新版本

📸 预览

PyTeXMK 预览 1 PyTeXMK 预览 2

🚀 快速开始

前置条件

在安装 PyTeXMK 之前，请确保你的系统已安装以下组件：

Python 3.14+（通过 uv 管理推荐）
LaTeX 发行版（任选其一）：
- Windows: MiKTeX 或 TeX Live
- macOS: MacTeX 或 BasicTeX
- Linux: TeX Live（发行版自带或官方安装）
可选工具（按需安装）：
- biber（biblatex 后端，用于参考文献处理）
- xindy（glossaries 后端，用于术语表编译）
- latexdiff（LaTeX 文件差异对比）

安装

通过 pip 或 uv

# 使用 pip 安装
pip install pytexmk

# 使用 uv 安装（推荐）
uv add pytexmk

Windows winget（推荐，无需 Python 环境）

winget install --id YanMing-lxb.PyTeXMK

升级

# pip
pip install --upgrade pytexmk

# uv（升级到最新版）
uv add pytexmk@latest

# winget
winget upgrade --id YanMing-lxb.PyTeXMK

基本使用

在 LaTeX 项目根目录下运行：

# 使用默认配置（XeLaTeX + main.tex + Build/）编译
pytexmk

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

# 使用 PdfLaTeX 编译
pytexmk -p main.tex

# 编译 + 预览 PDF
pytexmk main.tex -pv

# 清理辅助文件
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 文件。

📖 使用说明

编译引擎与模式

选项	说明
`-p`, `--PdfLaTeX`	使用 PdfLaTeX 编译
`-x`, `--XeLaTeX`	使用 XeLaTeX 编译（默认）
`-l`, `--LuaLaTeX`	使用 LuaLaTeX 编译
`-dr`, `--draft`	草稿模式，编译时不包含图片（加速）
`-nq`, `--non_quiet`	非安静模式，终端显示编译过程
`-vb`, `--verbose`	详细模式，显示 PyTeXMK 运行信息

清理

选项	说明
`-c`, `--clean`	清除主文件的辅助文件
`-C`, `--Clean`	清除辅助文件（含根目录）和输出文件
`-ca`, `--clean-any`	清除所有带辅助文件后缀的文件
`-Ca`, `--Clean-any`	清除所有辅助文件（含根目录）和主文件输出

LaTeXDiff 差异对比

选项	说明
`-d`, `--LaTeXDiff`	生成两个文件的差异对比，输出 `LaTeXDiff.tex`
`-dc`, `--LaTexDiff-compile`	生成差异文件并自动编译，输出带修订标记的 PDF

示例：

pytexmk -d old.tex new.tex     # 生成 LaTeXDiff.tex
pytexmk -dc old.tex new.tex    # 生成并编译 LaTeXDiff PDF

支持在参考文献和符号索引中显示修改痕迹，编译时会提示选择风格。

PDF 工具

选项	说明
`-pr`, `--pdf-repair`	修复损坏的 PDF 文件（如图片导致的 `invalid X X R object` 警告）
`-pv`, `--pdf-preview`	编译完成后调用浏览器或本地 PDF 阅读器预览

多子项目管理

PyTeXMK 支持在一个项目根目录下管理多个相互独立的子项目，各自拥有独立的编译配置和输出目录。

典型流程：

# 1. 生成根配置文件
pytexmk -i

# 2. 自动扫描并展示子项目清单（同时更新配置）
pytexmk -ls

# 3. 编译指定子项目（可与主文件名配合）
pytexmk -s 论文 main.tex

选项	说明
`-s`, `--subproject <名称>`	选中指定子项目并在其目录下编译/清理
`-ls`, `--list-subprojects`	扫描子项目并展示清单，同步更新根配置

配置文件生成

选项	说明
`-i`, `--init`	在当前目录生成项目级 `.pytexmkrc`
`-iu`, `--init-user`	在用户主目录生成用户级 `.pytexmkrc`
`-f`, `--force`	配合 `-i`/`-iu` 强制覆盖已存在的配置文件

其他

选项	说明
`document`	位置参数，指定要编译的文件名（可省略后缀）
`-h`, `--help`	显示帮助信息
`-v`, `--version`	显示程序版本号

魔法注释

PyTeXMK 支持在 LaTeX 主文件前 50 行使用魔法注释来自定义编译行为：

魔法注释	说明	示例
`% !TEX program = <引擎>`	指定编译引擎	`% !TEX program = PdfLaTeX`
`% !TEX root = <文件名>`	指定待编译主文件	`% !TEX root = main`
`% !TEX outdir = <目录>`	指定输出目录	`% !TEX outdir = output`
`% !TEX auxdir = <目录>`	指定辅助目录	`% !TEX auxdir = auxfiles`

注意：魔法注释仅在主文件中定义有效，子文件中的注释会被忽略。

工作原理

📂 主文件自动识别

命令行参数明确指定 → 使用该文件
当前目录仅一个 .tex 文件 → 自动选中
存在 % !TEX root 魔法注释 → 使用注释值
检索 \documentclass 或 \begin{document}（前 200 行）→ 识别主文件
默认回退到 main.tex

⚙️ 编译引擎选择

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

🔁 自动编译轮次

第一次编译 LaTeX
若 .aux 中存在参考文献引用，调度 bibtex / biber
若存在术语表/索引，调度 makeindex / xindy
继续编译 LaTeX，每轮结束后检测各维度是否收敛
所有维度稳定或达到安全上限后停止

配置文件说明

PyTeXMK 支持两级配置文件，均为 TOML 格式：

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

优先级：项目级 > 用户级 > 内置默认值

配置文件可通过 pytexmk -i（项目级）或 pytexmk -iu（用户级）生成模板，生成的模板中包含详细注释。

🛠 开发与构建

环境要求

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/

国际化工作流

# 新增语言
make lang-add

# 更新所有 pot/po
make lang-update

# 编译 po → mo
make lang-mo

# 重新抽取所有 pot 模板
make lang-poup

📄 许可证

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

📝 更新记录

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

🤝 参与贡献

欢迎提交 Issue 和 Pull Request！

🐛 遇到 Bug？请在 Issues 中提交
💡 有新功能建议？欢迎讨论
🌍 想帮助翻译？请查看国际化工作流

⭐ Star History

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