paper2kindle

Convert arXiv and SSRN papers into reflowable EPUB 3 documents and send them to Kindle.

The CLI is available as both paper2kindle and p2k.

Install

Install the published package from PyPI with uv:

uv tool install paper2kindle@latest
paper2kindle --version
p2k --help

To use optional Resend delivery, install the resend extra:

uv tool install 'paper2kindle[resend]@latest'

Upgrade an existing installation with uv tool upgrade paper2kindle.

EPUB conversion also requires the official external tools Pandoc, EPUBCheck. The setup wizard checks for both. Paper conversion runs locally; Docling may download its maintained models on first use.

Quick start

Run the first-time setup wizard, verify the configuration, then send a paper:

paper2kindle setup
paper2kindle doctor
p2k send 2401.12345

Setup and delivery

The interactive wizard configures your Kindle address and email delivery and is safe to rerun. To configure or inspect only one area, use one of the mutually exclusive scoped flags:

paper2kindle setup --kindle
paper2kindle setup --email
paper2kindle setup --tools
paper2kindle setup --storage

SMTP is the default. Setup records the host, port, STARTTLS or SSL mode, username, and sender; its password/token is stored in the OS keychain. Add that exact sender to Amazon's Approved Personal Document E-mail List. Credentials can instead be supplied with PAPER2KINDLE_SMTP_PASSWORD.

Resend is optional and requires a user-owned, Resend-verified sending domain:

paper2kindle setup --email  # choose resend

Its API key is stored in the keychain or read from PAPER2KINDLE_RESEND_API_KEY. Each user must provide their own key. Attachments over 29 MiB are rejected before contacting Resend.

Send EPUB by default, or explicitly request PDF. The document is temporary after a successful send unless retained with --keep or --output:

paper2kindle send 2401.12345
p2k send 2401.12345 --delivery resend --keep
p2k send ssrn:1234567 --format pdf --output paper.pdf
p2k send 2401.12345 --dry-run

--delivery is a one-command override and does not alter saved configuration. Dry runs prepare and retain the file without loading credentials or sending.

Supported sources

Only publicly accessible papers are supported. paper2kindle does not bypass authentication, paywalls, or source access controls.

Inspect and prepare

Inspecting only performs metadata requests; it does not download or convert the paper:

paper2kindle inspect 2401.12345
p2k inspect https://arxiv.org/pdf/hep-th/9901001.pdf
p2k inspect ssrn:1234567

EPUB 3 is the default and is never silently changed to PDF:

paper2kindle prepare 2401.12345
paper2kindle prepare ssrn:1234567 --output paper.epub
paper2kindle prepare 2401.12345 --format pdf --output paper.pdf
paper2kindle prepare 2401.12345 --strict --debug-artifacts ./debug

EPUB preparation requires pandoc and epubcheck. For arXiv, paper2kindle uses arXiv's official accessible HTML when available; otherwise it uses the published PDF with Docling while still producing EPUB. It never executes downloaded TeX. SSRN uses only publicly advertised PDF links on approved SSRN hosts and does not bypass access controls. Docling is installed as a Python dependency and may download its models on first use. --strict rejects source-fallback warnings, and --debug-artifacts retains conversion intermediates for diagnosis.

The converter checks output for missing structure and assets, fragmented text, unresolved LaTeX, degraded equations, encoding replacement characters, and a missing references section. Severe truncation always stops conversion; --strict also stops on quality warnings.

Security and privacy

• Downloads require HTTPS and are restricted to approved arXiv or SSRN hosts.
• Redirects, metadata, PDFs, and image assets are bounded and validated.
• Downloaded TeX is never executed. arXiv's official accessible HTML is used when available, with Docling PDF extraction as the EPUB fallback.
• Active HTML and SVG content is removed; raster figures are decoded, re-encoded, and embedded before Pandoc runs in sandbox mode.
• SMTP passwords and Resend API keys are stored in the OS keychain or supplied through environment variables. They are not written to the config file.
• The application does not collect telemetry.

PDF parsing and document conversion still process untrusted documents through third-party libraries. Run the CLI with the same care as other local document conversion software.

Development

Python 3.12+ and uv are required:

git clone https://github.com/markosnarinian/paper2kindle.git
cd paper2kindle
uv sync --all-extras
uv run pytest
uv run ruff check .
uv run pyright
uv build

The architecture and implementation roadmap are documented in PLAN.md.