Nano-PDF Editor

0.2.1 · active · verified Thu Apr 16

Nano-PDF is a command-line interface (CLI) tool that empowers users to edit PDF slides and documents using natural language prompts. Powered by Google's Gemini 3 Pro Image (also known as 'Nano Banana') model, it can perform tasks like updating charts, fixing typos, and adding new slides while preserving the PDF's searchable text layer through OCR re-hydration. The current version is 0.2.1, with recent updates indicating active development and a focus on incremental improvements.

Common errors

```
Missing system dependencies. Please install poppler and tesseract for your platform.
```
cause The required PDF rendering (Poppler) or OCR (Tesseract) tools are not installed or are not in your system's PATH.

fix Install Poppler and Tesseract specific to your operating system. For macOS: `brew install poppler tesseract`. For Ubuntu/Debian: `sudo apt-get install poppler-utils tesseract-ocr`. For Windows: `choco install poppler tesseract`. Afterwards, restart your terminal. You can verify installation by running `which pdftotext` and `which tesseract`.
```
GEMINI_API_KEY not found
```
cause The `GEMINI_API_KEY` environment variable, crucial for authenticating with the Gemini API, has not been set.

fix Set the API key as an environment variable before running the command: `export GEMINI_API_KEY="your_key_here"`. On Windows, use `set GEMINI_API_KEY=your_key_here` in cmd or `$env:GEMINI_API_KEY='your_key_here'` in PowerShell. For persistent storage, consider adding it to your shell's profile file (e.g., `.bashrc`, `.zshrc`) or using a `.env` file with `python-dotenv`.
```
Gemini API Error: PAID API key required
```
cause You are attempting to use the Gemini 3 Pro Image model with a free-tier API key, which does not support the necessary image generation features.

fix Access Google AI Studio, ensure your project has billing enabled, and generate an API key from an account with a paid billing tier.
```
Generated images don't match the style of the original PDF.
```
cause The Gemini model might not fully capture the visual style (fonts, colors, layout) of your existing PDF when generating new content or edits.

fix Use the `--style-refs` option to specify reference pages that have the desired visual style. For example, `--style-refs "1,5"` will tell the model to analyze pages 1 and 5 for styling cues.
```
Text layer is missing or incorrect after editing.
```
cause The OCR re-hydration process may not have accurately recognized or embedded the text, especially with low-resolution inputs or complex fonts.

fix Ensure your generated images are high resolution by using the `--resolution "4K"` option. While OCR may not be perfect, higher resolution generally improves accuracy.

Warnings

breaking The library heavily relies on external system-level dependencies like Poppler (for PDF rendering) and Tesseract (for OCR). These *must* be installed separately on your operating system for Nano-PDF to function, and their installation paths may need to be added to your system's PATH.
Fix: Install Poppler and Tesseract for your operating system (e.g., `brew install poppler tesseract` on macOS, `sudo apt-get install poppler-utils tesseract-ocr` on Ubuntu/Debian, `choco install poppler tesseract` on Windows). Restart your terminal after installation.
gotcha Nano-PDF requires a Google Gemini API key for image generation. Critically, this must be a *paid* API key, as free-tier Gemini keys do not support the necessary image generation features of Gemini 3 Pro Image.
Fix: Obtain a Google Gemini API key from Google AI Studio and ensure billing is enabled on your Google Cloud project. Set the key as an environment variable: `export GEMINI_API_KEY="your_key_here"`.
gotcha Page numbering in commands (e.g., `nano-pdf edit deck.pdf 1 ...`) can sometimes be 0-based or 1-based depending on internal versions or configurations, which might lead to off-by-one errors when targeting specific pages.
Fix: If results appear on an unexpected page, try adjusting the page number by one (e.g., if page 1 doesn't work, try page 0 or page 2). Always sanity-check the output PDF.
gotcha While Nano-PDF preserves the searchable text layer using OCR re-hydration, the accuracy can vary. Highly stylized fonts, small text, or complex layouts in the original PDF might result in imperfect or missing text selection after editing.
Fix: For best results, try increasing the `--resolution` to '4K' (though this might slow down processing). Be aware that OCR is not always perfect.
gotcha Processing large or multi-page PDFs can be slow, especially with high-resolution settings, due to the image rendering, AI generation, and OCR steps involved.
Fix: To speed up processing, consider using lower `--resolution` settings like '2K' or '1K'. For large documents, breaking edits into smaller, targeted commands might also help.

Install

pip install nano-pdf Install with pip

Quickstart

Nano-PDF is primarily a CLI tool. This quickstart demonstrates how to install its system dependencies, configure your Google Gemini API key, and perform basic PDF editing or slide generation using natural language commands.

# 1. Install system dependencies (Poppler and Tesseract OCR)
# macOS:
# brew install poppler tesseract

# Ubuntu/Debian:
# sudo apt-get install poppler-utils tesseract-ocr

# Windows (using Chocolatey):
# choco install poppler tesseract

# 2. Set your Google Gemini API key (requires a PAID API key)
# Replace 'YOUR_GEMINI_API_KEY' with your actual key
export GEMINI_API_KEY="$(os.environ.get('GEMINI_API_KEY', ''))"

# 3. Use Nano-PDF to edit a PDF (replace 'my_document.pdf' and prompt)
# Create a dummy PDF file for testing or use an existing one.
# Example: A PDF with a title on page 1.
nano-pdf edit my_document.pdf 1 "Change the title to 'Q3 2026 Financial Report'"

# Example: Add a new slide
nano-pdf add my_presentation.pdf 5 "Create an agenda slide with three bullet points: Introduction, Key Results, Next Steps"

view raw JSON →