meaningful-pdf-names 0.2.2

Offline-friendly PDF renamer that generates meaningful, keyword-rich filenames from PDF content.

Mac users: If you just want the ready-to-use macOS installer (right-click integration, no terminal required), head to Meaningful PDF Names — macOS DMG Release.

meaningful-pdf-names

Offline-friendly CLI to turn your messy paper filenames into compact, keyword-rich names based on the PDF's first page.

Example:

final_v3_really_final.pdf → urban-resilience-transport-inequality-policy-a9f.pdf

Features

• Uses the first 2 pages by default (title, authors, abstract, introduction) for better context
• Configurable page count with -p flag (e.g., -p 4 for 4 pages)
• Up to 5 meaningful keywords per file
• Adds a 3-character [a-z0-9] suffix to avoid collisions
• Works fully offline with pypdf + pdfminer.six fallback
• Optional: use a small local Hugging Face summarizer (sshleifer/distilbart-cnn-12-6) via transformers + torch

Prerequisites

• Python 3.9+ installed on your system
• pip (Python package manager) - usually comes with Python

Quick Install

From PyPI (Recommended)

pip install meaningful-pdf-names

Quick Start Guide

For Mac Users

1. Install the package (see above)
2. Navigate to your PDF folder:
   • Open Finder and go to the folder containing your PDFs
   • Right-click on the folder and select "New Terminal at Folder"
   • This opens Terminal directly in that folder
3. Run the command:

   mpn .
   

For Linux Users

1. Install the package (see above)
2. Navigate to your PDF folder:

   cd /path/to/your/pdf/folder
   

3. Run the command:

   mpn .
   

For Any Folder Location

If you want to rename PDFs in a different folder without navigating there:

mpn /full/path/to/your/pdf/folder

Usage Examples

Basic usage (current folder):

mpn .

Specific folder:

mpn ~/Downloads/research_papers
mpn /Users/username/Documents/PDFs

Single PDF file:

mpn document.pdf
mpn ~/Downloads/paper.pdf

Multiple PDF files:

mpn paper1.pdf paper2.pdf paper3.pdf
mpn ~/Downloads/*.pdf

Mixed files and folders:

mpn . document.pdf ~/Downloads/research_papers

Dry run (preview changes without renaming):

mpn . --dry-run
mpn document.pdf --dry-run

Quiet mode (minimal output):

mpn . --quiet

Custom page count (read more pages for better context):

mpn . -p 4          # Read first 4 pages
mpn . -p 10         # Read up to 10 pages (or all if PDF has fewer)
mpn document.pdf -p 3  # Read first 3 pages of specific file

What It Does

• Scans all PDF files in the specified folder
• Extracts text from first pages (-p, default 2) with quality checks
• Fallback order: pypdf -> pdfminer.six -> PDF metadata -> filename stem
• Identifies meaningful keywords from titles, authors, abstracts
• Generates clean, readable filenames like:
  • climate-change-urban-planning-sustainability-a9f.pdf
  • machine-learning-neural-networks-research-4x2.pdf
  • healthcare-policy-digital-transformation-b7c.pdf

Why Not Existing Tools?

Other tools often:

• Depend on OpenAI / web APIs (requires internet, API keys)
• Require DOIs or external metadata (not always available)
• Use long Author - Title - Year patterns (hard to read)

meaningful-pdf-names is:

• Local-only (no API keys, no network required)
• Fast (first-page only extraction)
• Slug-based: short, grep- and git-friendly names

License

MIT