Campus EZProxy

Log in once with your library; Paperful reuses that session and never stores the password. The walkthrough is How it works.

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. Bulk download can still violate an acceptable-use policy; see Research operators.

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 a headed browser (paperful session login ezproxy prefers system Chrome/Edge so campus SSO works); 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", "openaire", "direct", "ezproxy", "htmlpdf",
]

If you later opt in to Scholar or Sci-Hub, keep ezproxy before "scihub" so institutional access is preferred when both could work. Append "scholar" only after paperful session login scholar.

3. Log in (session vault)

uv run paperful session login ezproxy

Playwright ships in the paperful[browser] extra (and in the Compose image; uv sync --extra browser on the host). Chromium downloads on the first login if needed. doctor names the extra when the package is missing. Login prefers your system Chrome/Edge (Google and campus SSO often reject a Playwright-launched window). paperful ezproxy does the same. Complete campus SSO in the window that opens and wait until a publisher page loads through the proxy (the address bar should show your idm.oclc.org host, not only the CAS/IdP page), then press Enter. Paperful probes a proxied start URL, requires a proxy-host cookie, and writes state/sessions/storage_state.json plus Netscape mirrors (cookies.txt, ezproxy-cookies.txt). A CAS-only dump is rejected — that used to look “saved” and then expire mid-run. Never commit that directory.

4. Verify the session

uv run paperful session status
uv run paperful ezproxy --no-open

session status should say proxy-host ticket present (not CAS/IdP only). A live probe (ezproxy --no-open or doctor --probe) should report Session OK. If not, run session login ezproxy again.

5. Run (or retry) downloads

Publisher sites (especially Elsevier ScienceDirect) often 403 a cookie-only GET even when Unpaywall lists a PDF URL. After session login ezproxy, run opens those URLs in the vault Chromium profile (and wraps them in ezproxy_base) instead of stopping at download failed (HTTP 403). The profile follows an SSO hop, a citation PDF link, and a download control. Details: Sessions.

New runs pick up EZProxy when ezproxy is in sources and the session is valid. Before a long pass, confirm with paperful doctor --probe (or session status --probe):

uv run paperful doctor --probe
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

run probes the vault (Chromium profile when present, else cookies) before batch 1 when ezproxy is in sources. A dead session on a TTY with ezproxy_relogin (default on) prompts for headed login; decline or a non-TTY skips EZProxy wraps for that pass so OA lanes do not hammer campus CAS.

Library SSO typically lasts hours to a few days. When EZProxy starts failing mid-run you will see ezproxy:error(ezproxy session expired…) and later items skip the proxy. Soft-blocked OA PDF URLs that retry in the vault browser and land twice on campus CAS (login @federation…, or the older no download control @federation…) trip the same skip. On a TTY, run offers re-login once at the next batch boundary so later batches can use the proxy again. That prompt pauses the fetch progress bar so the question stays visible. Hosts that already failed hard in this run (publisher 403s, or vault landings that ended in login / captcha / no download control) are skipped for later items (host already blocked); that host set survives a mid-run re-login. Transport timeouts use a short connect budget and only silence a host after repeated blips. After the fetch, a TTY run still pauses for any items left session expired and retries only those. That browser is closed before the report and before --handoff opens tabs in your normal browser. Set ezproxy_relogin = false or pass --no-ezproxy-relogin to skip the pauses. Otherwise run paperful session login ezproxy, then another run (--retry-failed only if the misses were closed as not_found).

Confirm a live session with paperful doctor --probe or paperful session status --probe. Offline status should already show a proxy-host ticket; CAS-only means re-login. File presence alone is not enough to prove campus SSO is live.

Advanced: Netscape cookies.txt

If headed login is unavailable, paperful ezproxy can still use 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

  • Everyday browser login: already signed in to EZProxy in your usual browser does not feed Paperful. It never reads Chrome/Safari/Firefox cookies. Prefer session login ezproxy, or export Netscape cookies.txt (above). Same rule under Docker: headed login stays on the host; the container only reuses state/ — see Sessions and Docker.

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