nano-pdf

library0.2.1pypypiunverified

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.

llm-agents gcp ai-ml

pip install nano-pdf

github ↗package ↗

INSTALL

IMPORT

SIG · NANO-PDF

nano-pdf

llm-agentspythonv0.2.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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"

nano-pdf --version

Debug

Known issues

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

affects: All versions

gotchaNano-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"`.

affects: All versions

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

affects: All versions

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

affects: All versions

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

affects: All versions

Errors

Common errors & fixes

Missing system dependencies. Please install poppler and tesseract for your platform.

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

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

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.

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.

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.

Upgrade

Version history

0.2.1latest on PyPI · released Nov 29, 2025

Audit

Dependencies

pypdfrequiredCore PDF manipulation

pdf2imagerequiredConverts PDF pages to images for AI processing

typerrequiredPowers the command-line interface

pytesseractrequiredPython wrapper for Tesseract OCR for text re-hydration

pillowrequiredImage processing library (dependency of pdf2image/pytesseract)

google-genairequiredInteracts with Google Gemini API

python-dotenvoptionalOptional: Loads environment variables from .env files

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/gavrielc/Nano-PDF ↗

packagehttps://pypi.org/project/nano-pdf/ ↗