Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

papers

pypi python python test docs

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, push and sync exchange 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 of find and grep.
  • 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 redo take 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:  git
`papers status -v` shows all 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:  git
`papers status -v` shows all 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/

papers --help and papers <command> --help describe every command and option.

Install

papers 3 (beta, this branch) is not on PyPI yet:

pip install git+https://github.com/perrette/papers.git@v3

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

Speech to Text (dictate) and Text to Speech (read-aloud) tools

  • scribe — speech-to-text dictation.
  • bard — text-to-speech reader.

Metadata

Release files for papers-cli 3.0.0b1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for papers-cli 3.0.0b1
File Size Uploaded Provenance Actions
papers_cli-3.0.0b1.tar.gz 14.2 MB With provenance Details for papers_cli-3.0.0b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for papers-cli 3.0.0b1
File Interpreter ABI Platform Actions
papers_cli-3.0.0b1-py3-none-any.whl Python 3 none any Details for papers_cli-3.0.0b1-py3-none-any.whl

Total release size: 14.4 MB

Release files / papers_cli-3.0.0b1.tar.gz

Download URL papers_cli-3.0.0b1.tar.gz
Size 14.2 MB
Tags Source
SHA-256 checksum
How to use checksums
4d185f035d18468c57e06c62e15d4d5e0fe850b24b5a403ea3861886d0f3766f
BLAKE2b-256 checksum
How to use checksums
78d8fbb02e3703c6a436d16adf224dcfa411fd09a63a158ab437782e4be3d03a
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 24, 2026.

Transparency log

Release files / papers_cli-3.0.0b1-py3-none-any.whl

Download URL papers_cli-3.0.0b1-py3-none-any.whl
Size 197.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eda788f618889cf27482a9f9506382c8af537759a8ee8cdf66c55d32a821bc1a
BLAKE2b-256 checksum
How to use checksums
f2ad0e1578fcb01d38db37a3f347c0d38b3ce7b94485d2ca9d0aa908a2bc1d14
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 24, 2026.

Transparency log

Security for papers-cli 3.0.0b1

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.

Select from 2 files

Attestation for papers_cli-3.0.0b1.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 24, 2026.

Transparency log

A 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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page