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, CSL-JSON or BibJSON 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) or BibJSON (for programs).
  • Plain files: the bibtex is the database, the PDFs stay in folders you see, and the library can be edited with any tool.
  • Undo anything: every command is a step of the library's history, kept on your computer; papers undo / papers redo take back any command, with the files it moved, renamed or deleted, and a change made outside papers is never lost.
  • Fast on large libraries: the parsed bibtex is cached piece by piece, and papers status compares a project with its pool only where they changed.

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)
`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
`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/

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

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.0b5

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.0b5
File Size Uploaded Provenance Actions
papers_cli-3.0.0b5.tar.gz 14.2 MB With provenance Details for papers_cli-3.0.0b5.tar.gz

Built distribution (wheel)

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

Total release size: 14.5 MB

Release files / papers_cli-3.0.0b5.tar.gz

Download URL papers_cli-3.0.0b5.tar.gz
Size 14.2 MB
Tags Source
SHA-256 checksum
How to use checksums
b602ab2746bed6a0fbf6e03c697f0613b8ec049ea58516a7b5d843c4a2fd3fbc
BLAKE2b-256 checksum
How to use checksums
29d8d73a432a60af8a6e6e3887aa2a8eee448a71bbbf4f56da0296e7ecbcf0a9
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 28, 2026.

Transparency log

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

Download URL papers_cli-3.0.0b5-py3-none-any.whl
Size 233.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d251de24eea257f470798dcb264a09b51ef52e6336d1c2fdd7466c2b9597ddfa
BLAKE2b-256 checksum
How to use checksums
e709ee20a22d18e8715ea5b4dc0dff29500416ff43e1c7f427b7ca504db20aa1
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 28, 2026.

Transparency log

Security for papers-cli 3.0.0b5

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.0b5.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 28, 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