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:  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/

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

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.0b2
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)

Table of built distributions (wheels) for papers-cli 3.0.0b2
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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