Campus EZProxy¶

Publisher sites (Elsevier ScienceDirect, Springer Nature, Wiley, JSTOR, …) normally require a subscription. If your university or research library offers EZProxy (or a similar “login?url=” redirector), paperful can download those PDFs using your existing library entitlement.

What EZProxy will try¶

The campus proxy is only used where a library stanza can actually return a PDF:

Item has…	EZProxy?
A DOI	Yes — target is `https://doi.org/{doi}` (the usual path). The Zotero URL is ignored, so a webinar URL next to a real DOI is fine.
A URL on a known publisher host, and no DOI	Yes — the URL is wrapped in `ezproxy_base`. Subdomains match (`link.springer.com` counts as Springer).
Only a YouTube / `youtu.be` / Vimeo / X / Facebook / Zotero / Scholar link	No
Only an NGO, UN, or government page (FAO, High Seas Alliance, G77, …)	No — public sites are not in EZProxy databases. `direct` may still try them if the URL looks like a PDF.

Known publisher hosts (suffix match) include ScienceDirect / Elsevier, Springer Nature, Wiley, JSTOR, Taylor & Francis, Sage, Oxford, Cambridge, IEEE, ACM, Science, Cell, Lancet, NEJM, BMJ, PNAS, Annual Reviews, IOP, APS, RSC, ACS, AIP, Frontiers, MDPI, PLOS, Hindawi, De Gruyter, Brill, Emerald, SSRN, Ingenta, ProQuest, EBSCO, OECD / UN iLibrary, Project MUSE, HeinOnline, Westlaw, LexisNexis, Cairn, Érudit, OpenEdition, Persée, Dalloz, JAMA, World Scientific, MIT Press Direct, Chicago journals, Cochrane, Ovid, and BioOne.

The canonical list is _EZPROXY_PUBLISHER_HOSTS in paperful/routing.py. --try-all does not wrap YouTube or other non-publisher URLs.

The tool never asks for or stores your institutional password. You log in once in headed Chromium (paperful session login ezproxy); run reuses that vault and exported cookies until the campus session expires.

1. Find your library’s EZProxy base URL¶

Ask your library website for “EZProxy”, “off-campus access”, or “proxy bookmarklet”, or try the pattern many OCLC sites use:

https://<your-prefix>.idm.oclc.org/login?url=

Examples (illustrative only — use your institution’s URL):

Institution (example)	Typical `ezproxy_base`
Sciences Po	`https://scpo.idm.oclc.org/login?url=`
Other OCLC EZProxy	`https://<prefix>.idm.oclc.org/login?url=`

The value must be the prefix that, when a target URL is appended, starts login. A quick check in the browser: open

https://<your-prefix>.idm.oclc.org/login?url=https://www.sciencedirect.com/

You should land on your university’s single sign-on (CAS, Shibboleth, Microsoft, etc.). After login you should reach ScienceDirect (or an error from the publisher if your library does not subscribe — the login itself still proves the proxy URL is correct).

Some libraries use a hostname-rewriting proxy without login?url= (e.g. www-sciencedirect-com.proxy.example.edu). This tool expects the login?url= form. If your library only offers rewriting, ask them for the “start URL” / bookmarklet form, or leave EZProxy disabled.

2. Put the URL in `config.toml`¶

ezproxy_base = "https://YOUR-PREFIX.idm.oclc.org/login?url="
# optional — default is already state/ezproxy-cookies.txt under state_dir:
# ezproxy_cookies = "state/ezproxy-cookies.txt"

sources = [
  "unpaywall", "openalex", "arxiv", "biorxiv", "europepmc", "semanticscholar",
  "core", "scholar", "direct", "ezproxy", "htmlpdf",
]

If you later opt in to Sci-Hub, keep ezproxy before "scihub" so institutional access is preferred when both could work.

3. Log in (session vault)¶

uv sync --extra htmlpdf
uv run playwright install chromium   # or: playwright install chrome
uv run paperful session login ezproxy

paperful ezproxy does the same when Playwright is installed. Complete campus SSO in the window that opens, then press Enter in the terminal. Cookies are written under state/sessions/ (and compat state/ezproxy-cookies.txt). Never commit that directory.

4. Verify the session¶

uv run paperful ezproxy --no-open

Success looks like Session OK. If not, run session login ezproxy again.

5. Run (or retry) downloads¶

New runs pick up EZProxy when ezproxy is in sources and the session is valid:

uv run paperful run --collection YOUR_COLLECTION

Items already marked not_found from an earlier run are not retried unless you ask:

uv run paperful run --collection YOUR_COLLECTION --retry-failed

6. When the session expires¶

Library SSO typically lasts hours to a few days. When EZProxy starts failing you will see ezproxy:error(ezproxy session expired…) in paperful report. Fix: paperful session login ezproxy, then --retry-failed if needed.

Advanced: Netscape cookies.txt¶

If you cannot install Playwright, paperful ezproxy opens the system browser and you can still drop a Netscape cookies.txt at ezproxy_cookies (Firefox cookies.txt, Chrome Get cookies.txt LOCALLY — local-only exporters). chmod 600. Never commit or paste the file.

Alternatives and limits¶

Campus VPN: if VPN alone gives you full publisher access without EZProxy, you can leave ezproxy_base empty and still use OA sources (and Sci-Hub only if you opt in); VPN does not replace a session for this tool’s EZProxy source.
No subscription: EZProxy cannot unlock journals your library does not license.
Non-publisher URLs: YouTube, Zotero, FAO, and similar pages are never proxied — see What EZProxy will try. Public UN / process PDFs go through direct (URL rewrites) then htmlpdf.
Google Scholar: solve CAPTCHA in paperful session login scholar (same Chromium profile used during run). Cookie-only export is often not enough.
arXiv: already in the default list (by arXiv id, 10.48550/arxiv.… DOI, or strict title match).
bioRxiv / medRxiv: 10.1101/… DOIs via the Cold Spring Harbor details API; PDF URL built from the latest version.
Europe PMC: OA PDF links (including ?pdf=render) for PubMed Central deposits, by DOI.