This release is a pre-release and may not be stable for production use.
papers
Command-line tool to manage your bibliography (PDFs + BibTeX).
papers keeps a BibTeX file for each of your projects, and the PDFs that
go with it. Give it a PDF: it reads the DOI, fetches the entry from
crossref, renames the PDF after the entry and adds both to your project.
A project can use another library as its pool, and take its entries and
PDFs from there, so that each PDF is stored and fetched once.
It works like git: one papers command with subcommands, run inside a
project folder.
- Add papers from PDFs, DOIs, bibtex, RIS or CSL-JSON files, or whole folders. The DOI is read from the PDF, and the metadata comes from crossref (by DOI or full-text search), doi.org or google scholar.
- Name the PDFs with a template (
{authorX}_{year}_{title}by default), and attach supplements to an entry. - Share entries and PDFs between projects: a shallow project uses
another library as its pool, takes its entries from there and links to
its PDFs; any library can also exchange entries with another one
(
--pool PATH).papers pull,pushandsyncexchange the entries with a field-by-field three-way merge; each project keeps its own keys. - Search and act on a library with
papers list(tag, edit, delete, rename, fetch, deduplicate), in the style offindandgrep. - Detect duplicates by DOI, arXiv identifier, ISBN, or authors and title, and merge them.
- Export a selection as a library with copies of its PDFs, or as RIS and CSL-JSON (for Zotero, EndNote, pandoc).
- Plain files: the bibtex is the database. Every change is backed up
with git (when it is installed), and
papers undo/papers redotake it back or restore it.
Example
A project with its own PDFs, and a second project that uses it as pool:
$ cd ~/projects/sealevel
$ papers init
created the library ~/projects/sealevel
* bibtex: papers.bib
* files: files (the files directory of the library)
* backup: bibtex history (git)
`papers config` lists and sets the settings
$ papers add ~/Downloads/esd-4-11-2013.pdf
Added -> perrette_landerer2013: A scaling approach to project regional sea level rise and it... (doi:10.5194/esd-4-11-2013, file:1)
$ cd ~/projects/tides
$ papers init --pool ../sealevel
created the library ~/projects/tides
* bibtex: papers.bib
* files: in the pool (shallow library)
* pool: ../sealevel
* backup: bibtex history (git)
`papers config` lists and sets the settings
$ papers add --doi 10.5194/esd-4-11-2013
Added -> perrette_landerer2013: A scaling approach to project regional sea level rise and it... (doi:10.5194/esd-4-11-2013, file:1) [from pool ../sealevel]
$ papers add ~/Downloads/bg-8-515-2011.pdf
Added -> perrette_yool2011: Near-ubiquity of ice-edge blooms in the Arctic (doi:10.5194/bg-8-515-2011, file:1) [also added to pool ../sealevel]
$ grep "file =" papers.bib
file = {:../sealevel/files/perrette_et_al_2013_a-scaling-approach-to-project-regional-sea-level-rise-and-its-uncertainties.pdf:pdf},
file = {:../sealevel/files/perrette_et_al_2011_near-ubiquity-of-ice-edge-blooms-in-the-arctic.pdf:pdf},
The second project took the first entry and its PDF from the pool: no
request to crossref, and no second copy of the PDF. The paper it added is
in the pool too. papers sync later exchanges the changes made in either
project. A library kept for sharing, such as ~/Documents/papers, can be
the pool of all projects (papers init --shallow, see
A global shared library).
Documentation
Full documentation: https://perrette.github.io/papers/
- Installation (incl. external dependencies)
- Quickstart: a self-contained project, and a shallow project that uses it
- Upgrading from papers 2
- Adding entries
- Listing and searching
- Pools, shallow libraries, a global shared library
- Configuration
- Also: files, renaming files and keys, managing your library, export, git integration, undo/redo
papers --help and papers <command> --help describe every command and
option.
Install
papers 3 (beta), published on PyPI as a pre-release:
pip install --pre papers-cli
papers 2, the current release:
pip install papers-cli
The package is called papers-cli because another project is registered
on PyPI as papers; the command is papers. Python 3.11 or later is
needed. See the
installation page for
external dependencies.
The project is developed by one person and is still evolving: bug reports and contributions are welcome.
From the same author
A few other open-source tools I maintain.
Scientific writing & data
- texmark — write scientific articles in Markdown and convert them to journal-ready LaTeX/PDF.
- datamanifest — declarative, reproducible dataset management. (See also the datamanifest.toml format spec and the DataManifest.jl Julia port.)
Speech to Text (dictate) and Text to Speech (read-aloud) tools
Metadata
Release files for papers-cli 3.0.0b2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| papers_cli-3.0.0b2.tar.gz | 14.2 MB | With provenance | Details for papers_cli-3.0.0b2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| papers_cli-3.0.0b2-py3-none-any.whl | Python 3 | none | any | Details for papers_cli-3.0.0b2-py3-none-any.whl |
Total release size: 14.4 MB
Release files / papers_cli-3.0.0b2.tar.gz
| Download URL | papers_cli-3.0.0b2.tar.gz |
|---|---|
| Size | 14.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ef044f3357d363f48031cdb1bfb8dc73e5a94fd91e267c5610d06a11d5a1612d
|
|
BLAKE2b-256 checksum How to use checksums |
96d7002939b3e423cdca1d77aaf9513f5dbe08597dcfa408a555d692637507e2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logRelease files / papers_cli-3.0.0b2-py3-none-any.whl
| Download URL | papers_cli-3.0.0b2-py3-none-any.whl |
|---|---|
| Size | 197.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
59c05b17d6f5256bda5ddbde0c8d7136cec81a420ae8c9ee52d92eb815902cc4
|
|
BLAKE2b-256 checksum How to use checksums |
0e0632c5241f95dbe1e87d83a111b4c6ada7fed86bf5e338b7b281938086e8e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logSecurity for papers-cli 3.0.0b2
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for papers_cli-3.0.0b2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.