paperful documentation

paperful fills the gaps in your Zotero library: fetch missing PDFs, keep them in a folder tree that mirrors your collections, and attach them back.

Work happens on disk (out/, state/). Zotero is a library adapter. Open access first; campus EZProxy when you have a subscription; Sci-Hub is opt-in and off by default.

Preferred deploy: Docker Compose. Use uv when developing the package itself.

The GitHub README is the same first-run story. 0.x flags may still move; see releases.

Start here

• Docker (preferred deploy)
  • Prerequisites
  • Quick start
  • Environment and override
  • Custom playbook packs
  • Common commands
  • Image contents
  • Sessions and attach
  • Develop with uv
• Commands
  • Doctor
  • Dry-run
  • Exits
  • Run summary
  • Output
• Configuration (config.toml)
  • Grey literature playbooks
• Paperful architecture
  • Data flow
  • Disk artifacts
  • Library adapter
  • Identifiers and lint
  • PDF text
  • Circuit breaker
  • Sci-Hub and presets
  • Disk mirror vs cloud quota
  • Operator tooling
  • Report JSON (paperful.run_report.v1)
  • Grey literature
  • Related docs
• Releases and stability
  • Ladder
  • What 1.0 still owes operators

Using paperful

• Source routing and circuit breaker
  • HTML→PDF (web, news, blogs)
• Campus EZProxy
  • What EZProxy will try
  • 1. Find your library’s EZProxy base URL
  • 2. Put the URL in config.toml
  • 3. Log in (session vault)
  • 4. Verify the session
  • 5. Run (or retry) downloads
  • 6. When the session expires
  • Advanced: Netscape cookies.txt
  • Alternatives and limits
• Browser sessions (Scholar, EZProxy, publishers)
  • If you see Session not ready (Scholar)
• Sci-Hub

Product

• How paperful compares
• How paperful compares — reference
• Roadmap