folder2pdf

Convert a folder's contents (and its sub-folders) into a single PDF document.
Text and source-code files are included as readable content; image files are embedded with captions.
The output is useful for AI ingestion tools like NotebookLLM.

Installation

pip install folder2pdf

Usage

folder2pdf <folder> [<folder> ...] [options]

Arguments

Options

Examples

Convert a folder to PDF:

folder2pdf ./my-project -o my-project.pdf

Convert multiple folders into one PDF:

folder2pdf ./backend ./frontend -o project.pdf

Convert without images:

folder2pdf ./my-project -o my-project.pdf --no-images

Only include Python and Markdown files:

folder2pdf ./my-project -o my-project.pdf -e .py .md

Exclude test files and log files:

folder2pdf ./my-project -o my-project.pdf -b "tests/" "*.log"

Ignore .gitignore rules:

folder2pdf ./my-project -o my-project.pdf --no-gitignore

Skip empty files and limit output to 200 lines per file:

folder2pdf ./my-project -o my-project.pdf --no-empty-files --max-lines 200

Truncate each file at 5000 characters:

folder2pdf ./my-project -o my-project.pdf --max-chars 5000

What gets included

Text / source-code files (default extensions):

.txt .md .rst .csv .tsv .json .xml .yaml .yml .toml
.ini .cfg .conf .env .log .py .js .ts .jsx .tsx
.html .htm .css .scss .java .c .cpp .h .hpp .cs
.go .rs .rb .php .sh .bash .zsh .ps1 .bat .sql and more.

Image files (embedded with captions):

.png .jpg .jpeg .gif .bmp .webp .tiff

Skipped automatically:

• Hidden files and directories (names starting with .)
• Files matched by the .gitignore in the target folder (requires pathspec)
• Files matched by the --blacklist patterns
• Binary files without a recognised extension

Project Summary (cover page)

The generated PDF cover page includes a Project Summary section with:

• Total Files Processed – number of files included
• Total Lines of Code – combined line count across all text files
• Image Files – number of image files embedded
• Lines by Extension – per-extension line counts, sorted by descending count

Programmatic API

from folder2pdf.converter import convert

pdf_path = convert(
    folder="./my-project",
    output="my-project.pdf",
    include_images=True,
    extensions=None,          # None = use built-in defaults
    blacklist=["tests/", "*.log"],  # optional exclusion patterns
    use_gitignore=True,       # read & apply .gitignore in the folder
    no_empty_files=True,      # skip zero-byte text files
    max_lines=200,            # truncate each text file at 200 lines
)
print(f"PDF saved to {pdf_path}")

Dependencies

• fpdf2 — PDF generation
• Pillow — image processing
• pathspec — gitignore-style pattern matching