Skip to main content

arXiv Subscription Viewer

Review arXiv papers from your terminal. Keep a reading queue you can return to.

For researchers who follow a field or work through a literature search: scan abstracts, star promising papers, add notes, and export citations. Start with live arXiv search or browse saved subscription emails. Your review state stays on your machine; AI services are optional.

arXiv Subscription Viewer showing a paper list beside the selected abstract, with search, selection, and export shortcuts

Application capture from the development checkout, using fictional paper fixtures. The released interface may differ.

Website · Guides · PyPI · Changelog

Getting started

Install

Use uv to install the published package in an isolated tool environment. The application requires Python 3.13+; this command lets uv provision Python 3.13 if needed.

uv tool install --python 3.13 arxiv-subscription-viewer

First run

Open a terminal and load a small page of recent papers in artificial intelligence:

arxiv-viewer search --category cs.AI --mode page --max-results 20

Dismiss the first-run welcome with Enter. You should see up to 20 papers and the selected paper's details. This uses the arXiv API and needs an internet connection, but no account, API key, or local files. Replace cs.AI with your category. Omitting --mode page collects the newest matching submission day, which can take longer.

Already saving arXiv emails? Open arxiv-viewer browse from the directory containing your populated history/ folder. The history guide includes a complete input example.

If the command is missing or results do not load, follow first-run troubleshooting. arxiv-viewer doctor diagnoses your setup; warnings about optional features are not prerequisites for live search.

Install with pip instead

With Python 3.13+ installed, create and activate a virtual environment:

python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install arxiv-subscription-viewer

On Windows, use py -3.13 -m venv .venv, then .venv\Scripts\Activate.ps1 in PowerShell. Run the same first-run command above.

Typical flow

  1. Scan. Move with j / k or the arrow keys. Read the selected abstract in the details pane.
  2. Keep what matters. Press x to star a paper, n to add a note, and r to mark it read.
  3. Narrow the list. Press / and enter starred or unread. This filters the papers already loaded; A starts a new arXiv search.
  4. Take it into your work. Select papers with Space, then press E for the export menu. Save BibTeX, RIS, or CSV to a file, or copy Markdown to the clipboard.

Press ? for help, Ctrl+p for the command palette, and q to quit. Stars and notes persist when the same papers are loaded again. See export and collections for saved reading lists and metadata backups.

Choose a workflow

Highlights

  • A durable reading queue: stars, read state, tags, notes, collections, and scheduled reviews.
  • Fast review: keyboard navigation, structured filters, saved searches, and a quick-triage mode.
  • Portable results: citation exports, metadata backup, and PDF downloads and previews.
  • Optional research tools: citation context from Semantic Scholar, Hugging Face paper signals, and summaries or chat through a configured language-model provider.
  • Reading preferences: 11 themes, compact lists, and adjustable detail views. See the configuration reference.

Key bindings

The cheat sheet covers navigation, organization, research, and export. For the exact keys in your installed version:

arxiv-viewer keybindings

Reading layouts and named paper marks are covered in the cheat sheet.

Local data and optional services

Run arxiv-viewer config-path to find config.json, which stores preferences, review metadata, and session state. Caches normally live in cache.db beside it; existing installations may retain separate legacy cache files. Exports default to ~/arxiv-exports/ and PDFs to ~/arxiv-pdfs/. See storage and configuration.

Saved email text and local review state can be used without a network connection. Live search, uncached abstracts, PDF/figure retrieval, and enabled external integrations use the network. Semantic Scholar, Hugging Face, and LLM enrichment are disabled by default. Configured AI features send paper content and prompts to your chosen CLI or HTTP provider; a local client may still use a hosted service. API keys, when configured, are stored in local JSON.

The base install includes PDF preview support. Optional extras add faster fuzzy matching (fuzzy), local embeddings (semantic-fastembed, with model downloads), or learned triage (ml). See search setup, local triage, and LLM setup before enabling them.

Guides and help

Contributing

Bug reports, clearer documentation, and focused code changes are welcome. Start with contributing, or report an issue with your version and steps to reproduce. For package boundaries, read the architecture guide.

License

MIT · Created by Nicolas Sebastian Schuler. An independent project; not affiliated with arXiv.

Metadata

Release files for arxiv-subscription-viewer 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for arxiv-subscription-viewer 0.4.0
File Size Uploaded Provenance Actions
arxiv_subscription_viewer-0.4.0.tar.gz 1.5 MB With provenance Details for arxiv_subscription_viewer-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for arxiv-subscription-viewer 0.4.0
File Interpreter ABI Platform Actions
arxiv_subscription_viewer-0.4.0-py3-none-any.whl Python 3 none any Details for arxiv_subscription_viewer-0.4.0-py3-none-any.whl

Total release size: 1.9 MB

Release files / arxiv_subscription_viewer-0.4.0.tar.gz

Download URL arxiv_subscription_viewer-0.4.0.tar.gz
Size 1.5 MB
Tags Source
SHA-256 checksum
How to use checksums
60e32f612043c311c683f1a559461e830e1898e474086464f1629d5dbac397a9
BLAKE2b-256 checksum
How to use checksums
2b3717ce9f1354314559b2b096cfe2897feb4a36127498735a4ad8f7b88a249b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Sep 4, 2026.

Transparency log

Release files / arxiv_subscription_viewer-0.4.0-py3-none-any.whl

Download URL arxiv_subscription_viewer-0.4.0-py3-none-any.whl
Size 421.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
843cedc8125596e80475ce5a2b5ee210e5120c94d3bdb77c08da5c9ff1e03e0e
BLAKE2b-256 checksum
How to use checksums
79a10da10808316e5a280ba0169959fce9b7fc517caf972b3f3dccfdd52e1d99
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Sep 4, 2026.

Transparency log

Security for arxiv-subscription-viewer 0.4.0

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 arxiv_subscription_viewer-0.4.0.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 Sep 4, 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.

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