Guide to Papis command-line document and bibliography manager for researchers
Papis is a powerful command-line document and bibliography manager with over 2,000 GitHub stars, designed for researchers who prefer terminal-based workflows. Written in Python, it provides a fast, scriptable, and highly customizable alternative to GUI-based reference managers like Zotero or Mendeley.
The philosophy behind Papis is that bibliographic data should be stored in simple, human-readable files organized in a plain directory structure. Each document in a Papis library is a folder containing a YAML metadata file (info.yaml) and associated files (PDFs, supplementary materials, notes). This approach means your library is inherently portable, versionable with Git, and accessible through any tool that can read files and directories.
For researchers who spend most of their time in terminals, use Vim or Emacs for writing, and prefer scriptable tools over graphical interfaces, Papis offers a natural fit. It integrates with academic databases for metadata retrieval, supports BibTeX and BibLaTeX export, and provides an extensible plugin system for custom workflows. Despite its command-line interface, Papis also includes optional GUI pickers and a web interface for when visual browsing is helpful.
Install Papis using pip or your system package manager:
Via pip (recommended):
pip install papis
Via system package managers:
brew install papispacman -S papisnix-env -i papisInitial configuration: Papis stores its configuration in ~/.config/papis/config. Create a minimal configuration:
[settings]
default-library = research
[research]
dir = ~/Documents/papers
This tells Papis to manage a library called "research" stored in ~/Documents/papers. Each document you add will create a subdirectory within this path containing the document file and metadata.
Additional configuration options:
[settings]
default-library = research
editor = vim
file-browser = open
picktool = papis.pick
database-backend = papis
[research]
dir = ~/Documents/papers
use-cache = True
[books]
dir = ~/Documents/books
You can define multiple libraries (research papers, books, technical reports) each with their own directory and configuration.
Adding Documents: Add papers to your library from multiple sources:
# Add a PDF with automatic metadata retrieval via DOI
papis add paper.pdf --from doi 10.1038/s41586-024-07487-w
# Add from arXiv identifier
papis add --from arxiv 2401.12345
# Add from a BibTeX file
papis add paper.pdf --from bibtex reference.bib
# Add with manual metadata
papis add paper.pdf --set author "Smith, John" --set title "Deep Learning" --set year 2024
# Add from ISBN (for books)
papis add book.pdf --from isbn 978-0-13-468599-1
Searching and Browsing: Query your library with flexible search:
# Search by any field
papis open "author:smith AND year:2024"
# List matching documents
papis list "machine learning"
# Browse with an interactive picker
papis browse "neural networks"
# Export search results as BibTeX
papis export --format bibtex "deep learning 2024"
Document Operations:
# Open the PDF of a document
papis open "smith 2024"
# Edit metadata in your configured editor
papis edit "smith 2024"
# Rename and organize files
papis rename "smith 2024"
# Remove a document
papis rm "old paper 2015"
# Move between libraries
papis mv --lib books "programming textbook"
BibTeX Export: Generate BibTeX files for LaTeX projects:
# Export entire library
papis export --all --format bibtex > references.bib
# Export specific entries
papis export --format bibtex "author:smith" >> project.bib
# Export in BibLaTeX format
papis export --format biblatex "machine learning" > ml-refs.bib
Metadata Retrieval: Fetch or update metadata from online sources:
# Update metadata from DOI
papis update --from doi "smith 2024"
# Fetch metadata from CrossRef
papis update --from crossref "incomplete entry"
# Bulk update metadata for all items missing DOIs
papis update --from crossref --all
Terminal-Centric Research Workflow:
papis add paper.pdf --from doi 10.xxxx/xxxxxpapis open "paper title" to open in your PDF viewerpapis export --format bibtex "paper title" >> thesis.bibVersion Control Integration: Since Papis stores everything as files and directories, you can version your entire library with Git:
cd ~/Documents/papers
git init
git add .
git commit -m "Initial library snapshot"
This gives you full history of metadata changes, the ability to sync across machines, and collaborative library management through Git workflows.
Scripting and Automation: Papis exposes a Python API for custom scripts:
import papis.api
# Search the library programmatically
docs = papis.api.get_documents_in_lib("research")
ml_papers = [d for d in docs if "machine learning" in d.get("tags", "")]
# Export filtered results
for doc in ml_papers:
print(f"{doc['author']} ({doc['year']}). {doc['title']}")
Integration with Text Editors:
papis.vim plugin for searching and inserting citations without leaving the editorpapis.el for Org-mode and LaTeX integrationpapis list --all | fzfSyncing Across Machines: Use any file synchronization tool (Syncthing, rsync, cloud storage) or Git to keep your Papis library consistent across workstations. The plain-file storage format ensures compatibility regardless of platform.
Papis supports plugins for extended functionality:
Install plugins via pip:
pip install papis-zotero
papis zotero import --from-bibtex zotero-export.bib