google-research/arxiv-latex-cleaner · 上手攻略

仓库：google-research/arxiv-latex-cleaner
链接：https://github.com/google-research/arxiv-latex-cleaner
分类：academic-writing
作者：Tom
更新：2026-07-13

这是什么

arxiv-latex-cleaner 是 Google Research 出品的 LaTeX 论文清理工具，专门帮助研究者将论文 LaTeX 代码整理成符合 arXiv 上传规范的版本。它能自动删除注释、清理辅助文件、压缩图片、转换格式，将你杂乱的写作环境变成一个干净的提交包。

目前 6.9K+ Stars，是每一位向 arXiv 投稿研究者几乎必备的工具。

解决什么问题

向 arXiv 提交论文时，研究者常遇到这些头疼问题：

arXiv 有 50MB 大小限制，但论文包含了大量调试图片、巨型 PDF、原始数据
LaTeX 注释是公开可见的，你的 \todo{}、调试注释、作者笔记全部暴露在 PDF 里
aux/log/out 等辅助文件 上传后毫无用处，还占空间
未使用的 .tex 文件和图片 也被一股脑上传，导致包体积超标
tikzpicture 源代码 被直接暴露，可能造成格式错乱或知识泄露
自定义命令（如 \red TODO）在提交时希望还原为普通文本

arxiv-latex-cleaner 把这些问题全部自动化处理，你只需一行命令。

快速安装

要求：Python >= 3.9

# 方式1：pip 安装（最简）
pip install arxiv-latex-cleaner

# 方式2：Homebrew（macOS）
brew install arxiv_latex_cleaner

# 方式3：源码运行（无需安装）
git clone https://github.com/google-research/arxiv-latex-cleaner
cd arxiv-latex-cleaner/
python -m arxiv_latex_cleaner --help

核心用法

基本清理（最常用）

# 最基础用法：删除辅助文件 + 注释
arxiv_latex_cleaner /path/to/your/latex_project
# 输出到 /path/to/your/latex_project_arXiv/

# 带图片压缩的完整清理
arxiv_latex_cleaner /path/to/your/latex_project \
  --resize_images \
  --im_size 500 \
  --compress_pdf

配置文件模式（推荐用于重复使用）

将配置写入 cleaner_config.yaml，方便复用：

arxiv_latex_cleaner /path/to/latex --config cleaner_config.yaml

示例配置文件结构：

# cleaner_config.yaml 示例
resize_images: true
im_size: 500
compress_pdf: true
keep_bib: true           # 保留 .bib 文件
convert_png_to_jpg: true
png_quality: 85

保留特定图片不做压缩

arxiv_latex_cleaner /path/to/latex \
  --resize_images \
  --im_size 500 \
  --images_allowlist='{"images/im.png": 2000, "figures/main_result.pdf": 300}'

格式为 JSON 字符串：键为图片路径，值为像素（图片）或 dpi（PDF）。

删除自定义命令

# 完全删除命令（如 \todo{} 整体消失）
arxiv_latex_cleaner /path/to/latex \
  --commands_to_delete todo1 todo2 note

# 删除命令但保留内容（如 \red{text} → text）
arxiv_latex_cleaner /path/to/latex \
  --commands_only_to_delete red blue highlight

处理 TikZ 图片（防止源码泄露）

arxiv_latex_cleaner /path/to/latex \
  --use_external_tikz EXTERNAL_TIKZ_FOLDER

要求： 1. 在 LaTeX 中使用 \tikzsetnextfilename{picture_name} 声明文件名 2. 预先将 TikZ 图片编译成 .pdf 文件放入 EXTERNAL_TIKZ_FOLDER 3. 工具会自动将 \begin{tikzpicture}...\end{tikzpicture} 替换为 \includegraphics{}

自定义正则替换

在 cleaner_config.yaml 中定义替换规则：

replace_commands:
  - pattern: '\\\\figcomp\{([^}]+)\}\{([^}]+)\}\{([^}]+)\}'
    insertion: '\\parbox[c]{ \\2\\linewidth }{ \\includegraphics[width=\\3\\linewidth]{figures/\\1} }'
    description: "Replace figcomp command"

保留 .bib 文件（引用管理）

arxiv_latex_cleaner /path/to/latex --keep_bib

典型使用场景

场景 1：首次投稿 arXiv

论文写作用了大量注释、图片、辅助文件，上传前：

arxiv_latex_cleaner ./my_paper \
  --resize_images \
  --im_size 500 \
  --compress_pdf \
  --keep_bib \
  --commands_to_delete todo note COMMENT

场景 2：arXiv 包体积超标

50MB 限制超出，先尝试压缩图片：

arxiv_latex_cleaner ./my_paper \
  --resize_images --im_size 400 \
  --compress_pdf \
  --convert_png_to_jpg

若仍超标，逐步降低 --im_size 或将低优先级图片加入 allowlist。

场景 3：arXiv 审稿后需要重新提交

审稿过程中大量 \todo{} 注释和调试命令堆积，提交修订版前：

arxiv_latex_cleaner ./my_paper \
  --commands_to_delete todo note red_flag

坑与注意

Python >= 3.9 是硬性要求
如果系统 Python 版本较旧（如 macOS 系统 Python 2.7 或某些老 Linux 发行版），需要先升级 Python 或使用 conda/virtualenv 创建独立环境。
Homebrew 版本可能落后于 PyPI
建议优先使用 pip install，以获取最新版（当前最新约 v1.0.11）。
TikZ externalization 需要预先编译 PDF
--use_external_tikz 功能不是自动将 TikZ 编译成 PDF，而是要求你提前编译好。不少人第一次用会忽略这一点导致替换失败。
--commands_to_delete 与 --commands_only_to_delete 不可重复
如果同一个命令同时出现在两个参数中，工具会以默认行为（保留内容）为准，而非删除。
Windows 用户建议用 WSL2
工具大量依赖文件路径处理，Windows 兼容性有限。推荐在 WSL2 或 Linux/macOS 环境下使用。
output 文件夹命名规则
默认在输入文件夹后加 _arXiv 后缀生成新文件夹，不会覆盖原始文件。但如果你之前运行过，原有的 _arXiv 会被直接覆盖，请注意备份。
处理前建议 git 提交
虽然默认不修改原文件，但建议处理前做一次 git 提交，防止配置文件参数写错导致意外结果。

与同类对比

工具	Stars	特点	限制
arxiv-latex-cleaner	6.9K+	Google 出品，功能最全，TikZ/正则替换/图片压缩	仅命令行
overleaf 自带清理	—	Overleaf 编辑器内置，上传前可视化清理	依赖 Overleaf
arxiv-checker 类工具	—	检查 arXiv 规范符合性	仅检查不清理

arxiv-latex-cleaner 是目前功能最完整、社区认可度最高的 arXiv LaTeX 清理工具，Google 团队背书加上活跃维护，是学术写作工作流的必备环节。

一句话推荐结论

投稿 arXiv 前必跑的工具，Google 出品免费可靠，一行命令解决注释泄露、文件膨胀、格式错乱等所有头疼问题。

⚠️ 注意：处理前请先备份原文件，并确认 Python >= 3.9 环境。