PaperNym
Your research papers, named properly — automatically.
PaperNym watches your folders and renames academic PDFs from their real publication metadata.
Pronounced PAY-per-nim /ˈpeɪ.pər.nɪm/: “paper” + “-nym”, as in synonym.
1-s2.0-S0001457525001344-main.pdf
-> 2025_Islam_Evaluating_crash_risk_factors_of_farm_equipment_vehicles_on_county_and_non-county_roads.pdf
Publisher downloads arrive with names like 1-s2.0-S0001457525001344-main.pdf,
nihms-1234567.pdf or 2403.01234v2.pdf. PaperNym finds each paper's DOI or arXiv ID,
looks it up in free scholarly databases, checks that the record really belongs to the PDF,
and gives the file a name you can read, sort and search.
Contents
- Features
- Install
- Getting started
- Name formats
- How a paper is identified
- Safety
- Privacy
- API keys
- Command-line reference
- Settings and data
- Uninstall
- Development
- Roadmap
- Licence and credits
Features
- Hands-off. Lives in the system tray and renames new PDFs as soon as they land in a watched folder, such as Downloads or your papers folder.
- Accurate. Uses Crossref, doi.org, OpenAlex, Semantic Scholar and arXiv, and verifies every result against the PDF's own text. A file is left alone rather than given a wrong name.
- Works offline. When no service can be reached, papers are named from the PDF alone,
marked
_CHECK, and fixed automatically once the services are back. - Your names win. A file you rename by hand is never renamed again.
- Undo anything. Every rename is recorded; undo the last one, a whole batch, or any rename from History.
- 15 name formats, or your own. Year–author–title, citekeys, Zotero style, or a custom template with your own text, with a live preview.
- Preview first. Dry runs show
old -> newwith checkboxes before anything is renamed. - Each paper is looked up once. Lookups are cached, and copies of a known paper are named without a web call.
- Tray app and command line. One install gives you both, sharing the same settings and history.
- Light and dark themes, a keyboard-friendly interface, batched notifications, and Start at login.
Install
Windows (recommended)
- Download
PaperNym-Setup-<version>.exefrom the latest release. - Run it. It installs for your user account only (no administrator rights) into
%LOCALAPPDATA%\Programs\PaperNym. - PaperNym opens and walks you through choosing folders and a name format.
The installer always includes the command line. It adds papernym to your user PATH
(open a new terminal afterwards) and registers both programs with Windows. You can also
choose Start PaperNym when I log in and a desktop shortcut.
Requirements: Windows 10 or 11 (64-bit) and an internet connection for lookups.
From source (any platform with Python 3.10+)
git clone https://github.com/Xatta-Trone/papernym.git
cd papernym
python -m venv .venv
.venv\Scripts\activate # Linux: source .venv/bin/activate
pip install -e ".[gui]" # drop [gui] for the command line only
This gives you papernym (command line) and papernym-gui (tray app). A PyPI package and
tested Linux support are on the roadmap.
Getting started
Tray app
On first start a short welcome asks for:
- Folders to watch, with or without subfolders.
- A name format, with a preview on sample papers.
- An optional OpenAlex key and whether to start at login.
PaperNym then shows a dry run of the PDFs already in those folders. Untick anything you want to keep as it is, then confirm. From then on new PDFs are renamed as they arrive.
The main window, opened from the tray icon, has these tabs:
| Tab | What it is for |
|---|---|
| Activity | Live list of renames with search, filters and paging; open, show in folder, undo, refresh |
| Needs attention | Papers that could not be identified: enter a DOI, edit the details, retry, or ignore |
| Folders | Watched folders, subfolder switch, exclude patterns; double-click a row to open it |
| Naming | Preset or custom format, year mode, live preview; can re-apply to earlier renames |
| Sources | API keys, contact email, the title-search switch, and a test of every service |
| History | Every rename, grouped by batch, with undo and CSV export |
| General | Start at login, notifications, theme, diagnostics |
| About | Version, links and the update check |
Closing the window keeps PaperNym running in the tray; use Quit in the tray menu to exit.
Command line
papernym scan . --dry-run # preview names for the PDFs in this folder
papernym scan . # rename them (one pass; the folder is not watched)
To watch folders:
papernym add-folder "D:\Papers"
papernym set-format year_author_title
papernym scan --dry-run
papernym watch # scan, then keep watching until Ctrl+C
If a batch is not what you wanted:
papernym undo
Name formats
Pick one of the fixed presets (papernym formats lists them all with examples):
| Preset | Example |
|---|---|
year_author_title (default) |
2025_Smith_Deep_learning_for_crash_severity.pdf |
author_year_title |
Smith_2025_Deep_learning_for_crash_severity.pdf |
year_authors_title |
2025_Smith_et_al_Deep_learning_for_crash_severity.pdf |
authors_year_title |
Smith_et_al_2025_Deep_learning_for_crash_severity.pdf |
year_author_shorttitle |
2025_Smith_Deep_learning_for_crash_severity_prediction.pdf |
author_year_shorttitle |
Smith_2025_Deep_learning_for_crash_severity_prediction.pdf |
year_author_journal_title |
2025_Smith_Accid_Anal_Prev_Deep_learning.pdf |
author_year_journal |
Smith_2025_Accid_Anal_Prev.pdf |
title_author_year |
Deep_learning_for_crash_severity_Smith_2025.pdf |
title_only |
Deep_learning_for_crash_severity.pdf |
author_year |
Smith_2025.pdf |
citekey |
Smith2025DeepLearningForCrashSeverityPrediction.pdf |
author_year_title_spaces |
Smith (2025) Deep learning for crash severity.pdf |
authors_year_title_spaces |
Smith et al (2025) Deep learning for crash severity.pdf |
authors_year_title_zotero |
Smith et al - 2025 - Deep learning for crash severity.pdf |
Or write a custom template from the tokens {year} {author} {authors} {title}
{shorttitle} {journal} plus your own text:
papernym set-format --custom "[{journal}] {author} {year} - {shorttitle}" --word-sep " "
Notes:
- Titles are kept as long as the file name allows. That includes Windows' full-path limit, so names never break in deep folders.
- Accents are folded to plain letters (
Bermúdez→Bermudez). Titles in non-Latin scripts are kept as they are. - Year mode:
citation(default) uses the year the publisher cites;onlineuses the first online date. Set it withpapernym set-year. - Existing files are never overwritten. If two different papers would get the same name,
the title is lengthened until the names differ, or
_b,_cis added. A second copy of the same paper gets_dup2.
How a paper is identified
- DOI. DOIs from the PDF's properties and text are tried in order. Each is looked up in Crossref, doi.org, OpenAlex and Semantic Scholar until one answers. The returned title must match the PDF's text; a DOI that belongs to a cited reference is rejected.
- arXiv ID. From the text or the file name, looked up in arXiv and Semantic Scholar.
- Title search. Optional and on by default; see Privacy. A result is accepted only if the title matches closely and the first author's surname is printed on page 1.
- Nothing found. The file is left untouched and listed under Needs attention, where you can enter the DOI yourself.
Files that are clearly not papers, such as invoices, slides and forms, are left alone.
Safety
- Files are only ever renamed in place. They are never moved, overwritten, edited or deleted.
- Every rename is recorded in History before it counts, and it can be undone.
- A name you give a file by hand is respected from then on.
- Files that are still downloading are waited for; files open in another program are retried later.
- The tray app and the command line never rename at the same time. While the tray app is running, the command line's renaming commands politely refuse.
Privacy
PaperNym has no account, no analytics and no telemetry. The only things that leave your computer are:
| Sent | To | When |
|---|---|---|
| DOIs and arXiv IDs found in your PDFs | Crossref, doi.org, OpenAlex, Semantic Scholar, arXiv | Every lookup |
| Paper titles | Crossref, OpenAlex, Semantic Scholar | Only while Search by title is on (papernym set-title-search off to stop) |
| Your email address | Crossref, as its "polite pool" contact | Only if you set one |
| Version number | GitHub, to check for a newer release | Once a day; can be turned off under About |
File contents and file names are never sent.
API keys
All keys are optional. PaperNym works without any.
| Service | Why add a key | Where to get it |
|---|---|---|
| OpenAlex | Adds OpenAlex as a source; it is skipped without a key | openalex.org/settings/api (free) |
| Semantic Scholar | Avoids the shared rate limit of keyless calls | semanticscholar.org/product/api |
Add them on the Sources tab, or from the command line:
papernym set-key openalex YOUR_KEY
papernym set-key semanticscholar YOUR_KEY
papernym set-email you@university.edu # optional, for Crossref
Keys are kept in the system credential store: Windows Credential Manager, the Secret
Service (GNOME Keyring or KWallet) on Linux, or the Keychain on macOS. They are not
written to the settings file. Where no credential store exists, PaperNym falls back to the
settings file (readable only by you) and says so. The environment variables
OPENALEX_API_KEY and S2_API_KEY override stored keys.
Command-line reference
| Command | What it does |
|---|---|
scan [FOLDER] [--dry-run] [--no-subfolders] |
One pass over the watched folders, or over FOLDER only |
watch [--poll] |
Scan, then keep watching until Ctrl+C |
add-folder PATH [--no-subfolders] / remove-folder PATH |
Manage watched folders |
exclude PATTERN / exclude --remove PATTERN |
Skip matching files; a pattern ending in / skips folders |
formats / set-format PRESET |
List presets, or choose one |
set-format --custom "TEMPLATE" [--word-sep _|" "|-|none] |
Use your own template |
set-year citation|online |
Year mode |
set-title-search on|off |
Allow or stop title searches |
set-key openalex|semanticscholar KEY / set-email EMAIL |
Keys and contact email |
reformat [--dry-run] [--include-manual] |
Re-apply the current format to earlier renames |
undo [--last N] |
Revert the last batch, or the last N renames |
fix PATH --doi DOI |
Name a file from a DOI you supply |
status |
Counts by status and the files needing attention |
show |
Settings, folders and where keys are stored |
test-apis |
Check every metadata service with a known paper |
compare [FOLDER] |
Show what each source returns for each PDF; renames nothing |
Each output line starts with a tag: [ok] renamed, [check] named offline (marked
_CHECK), [?] not identified, [busy] file in use, [skip], [warn], [preview] or
[undo]. Colours are switched off when the output is redirected, when NO_COLOR is set,
or with --no-color. Exit codes: 0 success, 1 failure, 2 usage error.
Settings and data
| Windows | Linux | |
|---|---|---|
| Settings, history and cache | %APPDATA%\PaperNym |
~/.config/PaperNym (or $XDG_CONFIG_HOME/PaperNym) |
Set PAPERNYM_HOME to use a different folder. The tray app and the command line share it,
so a folder added in one shows up in the other.
To try PaperNym without touching your real settings or files:
papernym-gui --sandbox --show # installed app: PaperNym.exe --sandbox --show
The sandbox uses a temporary settings folder and a temporary copy of some sample papers.
Uninstall
Use Settings → Apps → Installed apps → PaperNym → Uninstall. The uninstaller removes
the program, its Start-menu and login entries, and the PATH entry. It asks whether to
remove your settings, history and saved keys too (the default is to keep them). Your PDFs
are never touched.
Development
pip install -e ".[gui,dev]"
python -m pytest -q
papernym-gui --sandbox --show --debug # run the tray app from source
docs/SPEC.mdis the full specification: behaviour, naming rules, edge cases.docs/BUILDING.mdcovers building the Windows exe and installer, and releasing.docs/PROGRESS.mdis the work log and milestone checklist.
Bug reports and ideas are welcome in
Issues. For a misnamed paper, include its
DOI and the output of papernym compare on that file, if you can.
Roadmap
- Windows tray app, command line and installer
- Code-signed Windows releases
- PyPI package (
pip install papernym/pipx install papernym) - Tested Linux support for the tray app and the command line
Licence and credits
PaperNym is released under the MIT licence © 2026
Xatta-Trone. The Windows build bundles Qt for Python
(PySide6, LGPL-3.0), linked dynamically. Licences of all bundled components ship in
THIRD_PARTY_LICENSES.txt.
Metadata is provided by Crossref, DOI.org, OpenAlex, Semantic Scholar and arXiv. Thank you to these services for keeping scholarly metadata open.
Metadata
Release files for papernym 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| papernym-0.1.2.tar.gz | 218.1 kB | With provenance | Details for papernym-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| papernym-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for papernym-0.1.2-py3-none-any.whl |
Total release size: 415.5 kB
Release files / papernym-0.1.2.tar.gz
| Download URL | papernym-0.1.2.tar.gz |
|---|---|
| Size | 218.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
acab98ad3c758eeb6420d5565bafbc2af6cd761002f5c9c635e50439667fefd3
|
|
BLAKE2b-256 checksum How to use checksums |
00eec0e8c3cbda57a34003b460496c567d8bcff535ba7ee09cba9f479ddda93f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / papernym-0.1.2-py3-none-any.whl
| Download URL | papernym-0.1.2-py3-none-any.whl |
|---|---|
| Size | 197.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8a82cf93046a9ef985bb1eaffcbdfd888d00375747208584db116161217d086d
|
|
BLAKE2b-256 checksum How to use checksums |
bcd3fc57daaf62c358cf0c98be998c6fe2dad47159e1dfa8dbe01ac90164a1a4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logSecurity for papernym 0.1.2
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.
Attestation for papernym-0.1.2.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 Nov 11, 2026.
Transparency logA 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.