papis/papis · 上手攻略

仓库：papis/papis
链接：https://github.com/papis/papis · 文档 https://papis.readthedocs.io/en/latest/ · PyPI https://pypi.org/project/papis/
分类：academic-writing（命令行文献 / 书目管理器）
作者：spark
更新：2026-08-14

是什么

papis 是一个"高度可扩展的命令行文献与书目管理器"，用 Python 写成（pip 即可安装），每个条目用一个人类可读、可手改的 .yaml 文件存书目元数据，PDF / 文档本体放在同目录下。它面向不愿意把整个学术库锁进商业 SaaS、但又想要一个能跑命令、能脚本化、能跟编辑器协作的工具的研究者。

核心定位（README 自述）："Powerful and highly extensible command-line based document and bibliography manager"——注意两个关键词："command-line" 和 "extensible"。CLI 是入口，可扩展是它跟 Zotero / JabRef / Mendeley 等桌面 GUI 工具最不一样的地方。

解决什么问题

文献管理里几个老大难：批量导入 DOI 自动拉元数据、跨工具互导 BibTeX、跟编辑器（Vim / Emacs / nvim）联动、纯 CLI 环境（SSH / 服务器 / Docker）也能用、不绑架你的数据格式。papis 把这五条都做进了默认 workflow：

papis add --from doi <doi> 自动从 DOI 拉作者 / 期刊 / 年份，省去手动键 metadata；
papis bibtex read mylib.bib import --all 从 BibTeX 导入，反向 papis export --all --format bibtex > mylib.bib 导出——和 LaTeX 工作流无缝；
一等公民的 Vim / Neovim / Emacs 插件（papis-vim、papis.nvim、papis.el）；
完全文本化存储，可 git 同步、Syncthing 同步、Dropbox 同步，不像 Zotero 库那样二进制文件满天飞；
暴露 Python API，可以写脚本扩展（README 原话："Hacking Papis is easy! Use the API to easily create your own custom Python scripts."）。

快速安装

最简方案就是 pip：

pip install papis

PyPI 当前稳定包名就叫 papis（README 给的就是这一行）。其它可选方案（conda、源码、system package）见官方文档的 Installation 章节。如果想跑 web UI（papis serve）或 Vim / Emacs 集成，需要单独装对应子项目。

环境依赖最小：Python 3.8+（具体下限未在 README 标注，⚠️ 建议自行 pip install papis 后用 papis --version 确认）；不强制要 LaTeX；要打开 PDF 的话本机需要有 PDF 阅读器，papis open 会调用系统命令。

核心用法

1) 初始化库并加 PDF

README 给的标准 4 步示例（可直接复制）：

# 1. 拉两个示例 PDF 到本地
wget https://www.gnu.org/s/libc/manual/pdf/libc.pdf
wget https://www.ams.org/notices/201304/rnoti-p434.pdf

# 2. 按 DOI 加条目（自动从 DOI 拉元数据）
papis add --from doi 10.1090/noti963 rnoti-p434.pdf

# 3. 手动键 metadata 加条目（不靠 DOI 时）
papis add libc.pdf \
  --set author "Sandra Loosemore" \
  --set title "GNU C reference manual" \
  --set year 2018 \
  --set tags programming \
  --confirm

# 4. 打开 / 编辑
papis open
papis edit

papis open 弹出 picker（picktool 可配置，默认是 rofi / dmenu / fzf / TUI 等实现之一），用方向键选条目、Ctrl-o 打开、Ctrl-b 浏览器查看、Ctrl-e 编辑、Ctrl-t 多选、F1 看完整快捷键。

2) BibTeX 互导

# 导入现有 BibTeX 库
papis bibtex read mylib.bib import --all

# 导出整库到 BibTeX（喂给 LaTeX / Overleaf）
papis export --all --format bibtex > mylib.bib

这是 papis 跟学术写作流衔接最关键的两条命令。

3) 搜索 / 标签

papis search author:einstein
papis search title:relativity
papis search tags:programming

（具体 query 语法以 papis search -h 输出为准；上面是 README 文档模式，⚠️ 我未逐条 fetch 子命令签名验证。）

4) 启动 Web 界面

papis serve
# 然后浏览器打开 http://localhost:8888

这条特别适合在平板或没有终端的设备上翻库。

5) 任何命令都带 help

papis -h         # 总览
papis add -h    # 子命令参数

典型适用场景

LaTeX 重度用户：写论文需要 BibTeX、又不想被 Zotero / Mendeley 绑架数据格式；
服务器 / 远程开发机上工作：没 GUI，只有 SSH，要管几百篇 PDF；
Vim / Emacs / nvim 用户：papis 是一等编辑器集成（papis-vim / papis.nvim / papis.el 是官方生态项目）；
想 git 同步 / Syncthing 同步文献库的协作者：每条目一个 .yaml 文件，diff 友好，PR 友好；
需要脚本扩展的极客：README 明示 Python API 可被脚本调用，可以写自己的下载 / 抓取 / 整理脚本。

常见工作流示例

用 git 管理文献库（推荐 setup）：

mkdir ~/papis-library && cd ~/papis-library
git init
# 配置 papis 使用这个目录
papis config set dir ~/papis-library
# 之后 papis add ... 会在 ~/papis-library/<author>-<year>-<title>/ 下生成
# 每个条目一个文件夹 + info.yaml + 文件本体
# 整个库都可以 git commit / push 到私有 remote，多设备同步

与 Zotero 互补：很多研究者用 Zotero 做"发现 + 抓全文 + 在 PDF 里读标注"，但导出 BibTeX 给 LaTeX；papis 可以反过来——用 Zotero 抓全文、用 papis 管 BibTeX 和 LaTeX 引用闭环。具体路径见 README 引用的博客 Zotero + Papis + Syncthing。

批量抓论文 references：Alejandro Gallo 博客介绍 papis explore 子命令用来"拿到一篇论文的参考文献列表"——非常适合做 literature review 时批量补充相关条目。

AI 增强（实验性）：papis-ask（Julian Hauser 维护）是 README 列出的"AI for Papis"子项目，把 LLM 接入 papis 库——可以自然语言查询"找出 2023 年以后关于 diffusion model 的所有论文"。

坑与注意

⚠️ Web UI / TUI 都是单用户本地服务：papis serve 默认 http://localhost:8888，没有认证，不要直接暴露到公网。多用户场景请走文档里提到的部署指南（README 未给出反向代理示例）。
⚠️ PDF 阅读器依赖：papis open 调用系统命令打开 PDF——Linux 上需要 xdg-open / mimeo / zathura 等，macOS 自带，Windows 默认走 SumatraPDF 或 Adobe。如果命令失败，看 papis doctor 或文档配置 picktool / open-tool 字段。
⚠️ DOI 自动拉元数据可能失败：--from doi 依赖外部 metadata 源（Crossref 等），网络受限时会降级或报错；fallback 是用 --set 手键。
⚠️ 子项目维护参差：README 列了 10 个周边项目（papis-rofi / papis-dmenu / papis-tui / papis-vim / papis.nvim / papis-el / papis-zotero / papis-libgen / papis-firefox / papis-ask），其中 2 个（papis-dmenu、papis-vim）README 标记 "Maintained by you?"，意味着维护者空缺。生产使用前 git log 一下活跃度。
⚠️ Python 版本下限未在 README 标注：本攻略未独立核验 python_requires，建议 pip install papis 后跑 papis --version 自行确认。
⚠️ 大库性能：未量化：10k+ 条目的库 cold-start picker 流畅度、搜索响应时间 README 没有 benchmark；建议自测。
⚠️ 多用户同步冲突：纯文本库的 git 同步是利器，但两个设备同时 papis add 同一个 DOI 可能产生冲突条目；解决办法是分工（一个设备主写）或加锁文件，工作流约束 > 工具能力。
⚠️ 元数据源差异：--from doi / --from arxiv 等 --from <source> 走不同 metadata 源，每个源字段不同；批量导入前小规模抽样，看 info.yaml 字段是否完整。

配置文件速览（值得一看）

papis 的配置文件层：默认 ~/.config/papis/config.yaml 或 ~/.papis/config。关键配置项（README + 文档综合，未逐条 fetch 最新 stable 文档核验）：

dir：默认库目录；
picktool：picker 实现，可选 rofi / dmenu / fzf / TUI 等；
open-tool：打开 PDF 的命令；
editor：默认编辑器；
default-library：多库切换时哪个是默认。

多库配置（不止一个研究方向）：

# ~/.config/papis/config.yaml
libraries:
  main:
    dir: ~/papis/main
  side-project:
    dir: ~/papis/side
default-library: main

papis -l side-project search ... 切到 side-project 库搜索。这种 YAML-in-YAML 的层级设计是 papis 区别于 Zotero SQLite 库的关键。

与同类对比

README 自己列了 8 个同类项目，归纳如下：

工具	类型	关键差异（vs papis）
Zotero	桌面 GUI + 浏览器插件	生态最广、有 Word/LibreOffice 插件、SQLite 库；papis 是 CLI + 文本库
JabRef	Java 桌面 GUI	BibTeX 原生、强参考文献编辑；papis 不绑定 Java 生态
Mendeley	商业桌面	已停产 / 被 Elsevier 边缘化；papis 完全开源
cobib	Python CLI	跟 papis 最接近，CLI-first、BibTeX 原生，但生态比 papis 小
bibman / bibiman	CLI	更轻量但社区活跃度远低于 papis
pubs	CLI	Scheme 写的，生态小众
Xapers	CLI + Emacs	强 Emacs 绑定

核心权衡：Zotero / JabRef 适合"图形界面 + 大生态"，papis / cobib 适合"纯文本 + 可脚本 + Vim/Emacs"。

一句话推荐

如果你主要在终端 / Vim / nvim / Emacs 工作、想要完全文本化的 BibTeX 兼容库、又不怕写 Python 脚本扩展，papis 是 Zotero / JabRef 之外最值得认真试的 CLI 文献管理器；否则桌面 GUI 生态仍是 Zotero / JabRef 更稳。