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, google scholar or OpenAlex.
  • 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.0b7

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

Built distribution (wheel)

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

Total release size: 16.3 MB

Release files / papers_cli-3.0.0b7.tar.gz

Download URL papers_cli-3.0.0b7.tar.gz
Size 16.0 MB
Tags Source
SHA-256 checksum
How to use checksums
09ae63b64e73811603fc2080d657f1392e852f986072d5d973a0cf72bef17d9a
BLAKE2b-256 checksum
How to use checksums
8e13d47311f6aa0639eb7b93d9b837cc48cd72616768fdab2773feae4c34df4b
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 31, 2026.

Transparency log

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

Download URL papers_cli-3.0.0b7-py3-none-any.whl
Size 281.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
08c0bd3616d19353e76a7cef4f6c7f8d3e29b7c7b5f114e17a3d3e71d37308ed
BLAKE2b-256 checksum
How to use checksums
576b4c247876b9036949348dc5b9565f53226b95a5b9c9b702eee67b8143b89e
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 31, 2026.

Transparency log

Security for papers-cli 3.0.0b7

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.0b7.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 31, 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