Documentation

Complete guide to using NameMyPdf.

Table of Contents

  1. TOC

Basic Usage

Open With

The simplest way to use NameMyPdf:

  1. Open the Finder
  2. Locate and select PDF files you want to rename
  3. Right Click and choose Open With and select NameMyPdf
  4. Watch as they’re automatically renamed!

A progress window will show you what’s happening. The app will quit automatically when done.

How It Works

NameMyPdf follows this process for each PDF:

  1. Scans the first 2 pages of the PDF for a DOI (very old PDFs may not have this)
  2. Queries CrossRef API for metadata (author, year, title) (See example)
  3. Generates a clean filename: Author Year - Title.pdf
  4. Renames the file in place
  5. Logs old and new names to $HOME/Library/Logs/NameMyPdf.log

Filename Format

By default, files are renamed as:

Author Year - Title.pdf

Examples:

Original Renamed
paper.pdf Smith 2023 - Machine Learning Applications.pdf
download.pdf Johnson 2024 - Neural Networks Deep Learning.pdf
arxiv-1234.pdf Chen 2023 - Computer Vision Transformers.pdf

Configuration

NameMyPdf creates a configuration file at ~/.namemypdfrc on first run (To edit later use Command+Shift+. to display hidden files in either the Finder or TextEdit)

Configuration Options

Including your email address makes it possible for Crossref to track the number of users or contact you if you’re causing a problem (like by renaming thousands of files? See this link for their explanation).

# Email for CrossRef API (recommended for heavy usage)
CROSSREF_EMAIL=you@email.com

# Convert title to lowercase
DOWNCASE_TITLE=false

# Number of words from title to include
TITLE_WORDS=7

# Separator between title words
TITLE_WORD_SEPARATOR=" "

# Separator between author and year
AUTHOR_YEAR_SEPARATOR=" "

# Separator between year and title
YEAR_TITLE_SEPARATOR=" - "

# Use abbreviated title (first letter of each word)
USE_ABBR_TITLE=false

# Remove everything after colon in title
STRIP_TITLE_POST_COLON=true

# Enable logs for debugging (probably not necesssary) and logging
DEBUG=false
LOG=true

Example Configurations

Shorter filenames:

TITLE_WORDS=4
STRIP_TITLE_POST_COLON=true

Result: Smith 2023 - Machine Learning Applications.pdf

Abbreviated titles:

USE_ABBR_TITLE=true
TITLE_WORD_SEPARATOR=""
AUTHOR_YEAR_SEPARATOR=""

Result: Smith2023MLA.pdf

All lowercase:

DOWNCASE_TITLE=true

Result: smith 2023 - machine learning applications.pdf

Command-Line Usage

For terminal users, you can install the command-line tool.

Installation 

/Applications/NameMyPdf.app/Contents/Resources/install-cli.sh

This creates a namemypdf command in /usr/local/bin.

Usage 

# Single file
namemypdf paper.pdf

# Multiple files
namemypdf paper1.pdf paper2.pdf paper3.pdf

# All PDFs in current directory
namemypdf *.pdf

# All PDFs in a subdirectory
namemypdf ~/Downloads/*.pdf

Uninstall CLI 

sudo rm /usr/local/bin/namemypdf

Logs and Debugging

NameMyPdf logs all activity to ~/Library/Logs/NameMyPdf.log (or “$HOME/.namemypdf.log” on non-Macs)

Enable Debug Mode

Edit ~/.namemypdfrc and set:

DEBUG=true

This will show detailed information about:

  • Tool paths (pdftotext, jq, curl)
  • DOI extraction
  • API responses
  • Filename generation

Troubleshooting

No DOI Found

Problem: “No DOI found in [filename], skipping”

Solutions:

  • Make sure the PDF contains a DOI in the first two pages. Many older PDFs do not follow this convention.
  • If you see the DOI and think that there’s a bug in how the script detects DOIs, please open an issue and describe why you think the script might not have found the DOI. I

Resource Not Found

Problem: “[DOI] — not found”

Explanations and things to try:

  • The DOI exists in the PDF but isn’t in CrossRef database
  • Try manually looking up the DOI at https://doi.org/
  • The DOI might be malformed or incorrect
  • Publishers are surprisingly bad at having correct data in the database. I’ve seen missing authors (on my own article!) and trash thrown into various fields. It’s almost certainly a problem with the data provided by the publisher, but there could be some edge cases that have not yet been identified. If it looks like the data in the DOI database is correct but the file isn’t renamed as expected, Open an issue with the DOI.

File Not Renamed

Problem: File already exists with the target name

Solution: NameMyPdf won’t overwrite existing files. Rename or move the existing file first.

FAQ

Does this work with non-academic PDFs?

No, NameMyPdf specifically looks for DOI information, which is typically only in academic papers. PDFs without a DOI on the first two pages won’t be renamed.

How come nothing happens the first time I use “Open With”?

This is a known problem. If the app hasn’t been opened the filename isn’t passed to the script that does the work until you click the NameMyPdf menu at the top of the screen or just try it again. I spent an entire day trying to save you making this extra click and failed. I’m very sorry.

How can I change the format of the filename?

Choose “Settings” from the NameMyPdf “status Icon” (I can’t get it be be an icon, so it’s a word) on the Menu Bar. It opens TextEdit. Change the values, save, and quit. Then rename again.

Can I undo a rename?

Not automatically, but the log file (accessible from the menu) shows what was renamed and when. You can manually rename files back if needed.

I want a name that isn’t possible with the available settings. What can I do?

Open an issue and explain what format you want and make a suggestion. I would want the author in lower case, but I’m no longer an academic, so until someone else wants that, I’m not going to spend the time.

Does it modify the PDF content?

No! NameMyPdf only renames the file. The PDF content is never modified.

What if I have thousands of files?

NameMyPdf can handle batch processing. However, be courteous to the CrossRef API - consider adding your email to the config file if processing many files.

Does it work offline?

No, NameMyPdf needs internet access to query the CrossRef API for metadata.

Is my data sent anywhere?

Only the DOI is sent to the CrossRef API when you make the request for the data. No file contents or personal data is transmitted.

I’ve installed a bunch of versions and now see multiple versions in Open With

See this discussion on an Apple Forum. They say to paste this command into a terminal to fix it:

/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -kill -r -seed -domain local -domain system -domain user

Need More Help?