PDFCraft — 轻量级本地 PDF 智能工具箱 | Lightweight Local PDF Smart Toolbox
🇨🇳 简体中文 | 🇹🇼 繁體中文 | 🇺🇸 English
一站式 PDF 处理解决方案，16 项核心功能，完全本地运行，无需上传文件到云端。
在日常办公和学习中，PDF 文件的处理几乎无处不在——合并报告、拆分合同、添加水印、压缩文件体积……然而市面上大多数 PDF 工具要么功能臃肿、收费高昂，要么需要将文件上传到云端，存在隐私泄露的风险。
PDFCraft 正是为了解决这些痛点而诞生的：
| 痛点 | PDFCraft 的解决方案 |
|---|---|
| 云端工具隐私风险 | 完全本地处理，文件不离开你的电脑 |
| 在线工具收费昂贵 | 开源免费，MIT 协议，无任何限制 |
| 功能分散在多个工具 | 16 合 1，一个工具覆盖所有常见需求 |
| 命令行工具门槛高 | 提供 CLI + TUI + GUI 三种交互方式 |
| 安装配置复杂 | 一条命令安装，开箱即用 |
核心定位：轻量、快速、安全、易用。不追求大而全，而是把每一项功能做到极致。
PDFCraft 提供 16 项核心功能，覆盖 PDF 处理的方方面面：
| 序号 | 功能 | 说明 |
|---|---|---|
| 1 | 📎 PDF 合并 | 多文件智能合并，自动生成目录书签 |
| 2 | ✂️ PDF 拆分 | 按页码、范围或章节灵活拆分 |
| 3 | 🖼️ PDF 转图片 | 高清 PNG/JPG 导出，自定义 DPI |
| 4 | 📸 图片转 PDF | 批量图片智能合成 PDF 文档 |
| 5 | 🗜️ PDF 压缩 | 智能压缩算法，在体积与质量间取得平衡 |
| 6 | 💧 水印添加 | 支持文字/图片水印，自定义位置与透明度 |
| 7 | 🔒 PDF 加密 | AES-256 强加密，密码保护你的文档 |
| 8 | 🔓 PDF 解密 | 快速移除 PDF 密码保护 |
| 9 | 🔄 页面旋转 | 精确到每一页的旋转控制 |
| 10 | ✂️ 页面裁剪 | 精确到毫米的页面裁剪 |
| 11 | ℹ️ 元数据查看 | 一键查看 PDF 文档详细信息 |
| 12 | ✏️ 元数据编辑 | 修改标题、作者、关键词等元信息 |
| 13 | 📝 文本提取 | 高精度提取 PDF 中的文本内容 |
| 14 | 🖼️ 图片提取 | 提取 PDF 中嵌入的所有图片 |
| 15 | ⚡ 批量处理 | 多文件并行处理，效率翻倍 |
| 16 | 🖥️ TUI 交互界面 | 终端中的可视化菜单，告别记命令 |
- Python >= 3.8
- 操作系统：Windows / macOS / Linux
# 从 PyPI 安装（推荐）
pip install pdfcraft
# 或从源码开发模式安装
git clone https://github.com/your-org/pdfcraft.git
cd pdfcraft
pip install -e .pdfcraft --version
# 输出: pdfcraft, version 1.0.0
pdfcraft --help
# 查看所有可用命令# 1. 命令行模式（CLI）—— 适合脚本和自动化
pdfcraft merge file1.pdf file2.pdf -o merged.pdf
# 2. 终端交互模式（TUI）—— 适合日常使用
pdfcraft tui
# 3. 图形界面模式（GUI）—— 适合非技术用户
pdfcraft gui将多个 PDF 文件合并为一个，支持自动生成目录书签。
# 基本合并
pdfcraft merge file1.pdf file2.pdf file3.pdf -o merged.pdf
# 合并整个目录下的 PDF
pdfcraft merge ./reports/*.pdf -o all-reports.pdf
# 合并并生成书签（以文件名作为书签）
pdfcraft merge file1.pdf file2.pdf -o merged.pdf --bookmarks按页码、范围或章节灵活拆分 PDF。
# 按页码范围拆分
pdfcraft split input.pdf -r "1-3,5,7-10" -o output_dir/
# 每隔 N 页拆分
pdfcraft split input.pdf -n 5 -o output_dir/
# 拆分为单页
pdfcraft split input.pdf --each -o output_dir/将 PDF 页面导出为高清图片。
# 导出为 PNG，默认 150 DPI
pdfcraft pdf2img input.pdf -o images/
# 自定义 DPI 和格式
pdfcraft pdf2img input.pdf -o images/ --dpi 300 --format jpg
# 仅导出指定页面
pdfcraft pdf2img input.pdf -o images/ -r "1,3,5-8"将多张图片合成为一个 PDF 文档。
# 基本转换
pdfcraft img2pdf img1.png img2.jpg img3.png -o output.pdf
# 批量转换目录下的图片
pdfcraft img2pdf ./photos/*.jpg -o album.pdf
# 自定义页面尺寸
pdfcraft img2pdf img1.png img2.png -o output.pdf --pagesize A4智能压缩 PDF 文件，在体积和质量之间取得最佳平衡。
# 默认压缩（质量因子 0.7）
pdfcraft compress input.pdf -o compressed.pdf
# 指定压缩质量（0.0 ~ 1.0，越小体积越小）
pdfcraft compress input.pdf -o compressed.pdf -q 0.5
# 极限压缩（体积最小）
pdfcraft compress input.pdf -o compressed.pdf -q 0.3为 PDF 添加文字或图片水印。
# 添加文字水印
pdfcraft watermark input.pdf -o watermarked.pdf -t "CONFIDENTIAL"
# 自定义水印样式
pdfcraft watermark input.pdf -o watermarked.pdf \
-t "内部文件" \
--opacity 0.3 \
--angle 45 \
--fontsize 60 \
--color "#FF0000"
# 添加图片水印
pdfcraft watermark input.pdf -o watermarked.pdf \
--image logo.png \
--opacity 0.2使用 AES-256 算法为 PDF 添加密码保护。
# 基本加密
pdfcraft encrypt input.pdf -o encrypted.pdf -p mypassword
# 设置权限（禁止打印/复制/编辑）
pdfcraft encrypt input.pdf -o encrypted.pdf -p mypassword \
--no-print --no-copy --no-edit移除 PDF 的密码保护。
pdfcraft decrypt encrypted.pdf -o decrypted.pdf -p mypassword精确旋转 PDF 的指定页面。
# 所有页面旋转 90 度
pdfcraft rotate input.pdf -o rotated.pdf --angle 90
# 仅旋转指定页面
pdfcraft rotate input.pdf -o rotated.pdf -r "1,3,5" --angle 180精确裁剪 PDF 页面。
# 按边距裁剪（单位：毫米）
pdfcraft crop input.pdf -o cropped.pdf \
--left 20 --right 20 --top 30 --bottom 30
# 按比例裁剪
pdfcraft crop input.pdf -o cropped.pdf --ratio 0.9查看 PDF 文档的详细元信息。
pdfcraft info input.pdf
# 输出示例：
# 文件名: input.pdf
# 页数: 42
# 标题: Annual Report 2025
# 作者: PDFCraft Team
# 创建时间: 2025-01-15 10:30:00
# 文件大小: 3.2 MB
# PDF版本: 1.7修改 PDF 的元数据信息。
pdfcraft metadata input.pdf -o output.pdf \
--title "年度报告 2025" \
--author "张三" \
--subject "财务报告" \
--keywords "年报,财务,2025"高精度提取 PDF 中的文本内容。
# 提取全部文本
pdfcraft extract-text input.pdf -o output.txt
# 提取指定页面
pdfcraft extract-text input.pdf -o output.txt -r "1-5"
# 输出为 Markdown 格式
pdfcraft extract-text input.pdf -o output.md --format markdown提取 PDF 中嵌入的所有图片。
# 提取所有图片
pdfcraft extract-images input.pdf -o images/
# 仅提取指定页面的图片
pdfcraft extract-images input.pdf -o images/ -r "3-10"
# 指定输出格式
pdfcraft extract-images input.pdf -o images/ --format png对多个文件执行相同操作，支持并行处理。
# 批量压缩
pdfcraft batch compress ./reports/*.pdf -o ./compressed/ --parallel 4
# 批量添加水印
pdfcraft batch watermark ./contracts/*.pdf -o ./watermarked/ -t "机密"
# 批量加密
pdfcraft batch encrypt ./docs/*.pdf -o ./encrypted/ -p mypassword启动终端交互式菜单，无需记忆任何命令。
pdfcraft tui启动后，你将看到一个可视化的功能菜单，通过方向键选择、回车确认即可完成操作。适合日常使用和不熟悉命令行的用户。
- 本地优先：所有处理在本地完成，文件零上传，隐私零风险
- 模块化架构：每个功能独立模块，按需加载，启动迅速
- 渐进式交互：CLI 适合自动化，TUI 适合交互式使用，GUI 适合图形化操作
- 零外部依赖：核心功能不依赖任何在线服务，离线可用
| 组件 | 技术 | 用途 |
|---|---|---|
| PDF 引擎 | PyMuPDF (fitz) | 高性能 PDF 读写 |
| CLI 框架 | Click | 命令行接口构建 |
| 终端美化 | Rich | 彩色输出、进度条、表格 |
| 交互界面 | Prompt Toolkit | TUI 终端交互 |
| 图形界面 | Tkinter | GUI 图形界面 |
- v1.0.0 — 16 项核心功能，CLI + TUI + GUI
- v1.1.0 — OCR 文字识别，支持扫描件 PDF
- v1.2.0 — PDF 表单填写与创建
- v2.0.0 — PDF 编辑（插入/删除页面，添加标注）
- v2.1.0 — 插件系统，支持第三方功能扩展
- v3.0.0 — Web UI，浏览器中操作 PDF
# 安装构建工具
pip install build
# 构建
python -m build
# 产物在 dist/ 目录下
ls dist/
# pdfcraft-1.0.0-py3-none-any.whl
# pdfcraft-1.0.0.tar.gz# 安装 Twine
pip install twine
# 上传
twine upload dist/*# 安装 PyInstaller
pip install pyinstaller
# 打包为单文件
pyinstaller --onefile --name pdfcraft src/pdfcraft/main.py
# 产物在 dist/pdfcraft（或 dist/pdfcraft.exe）FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -e .
ENTRYPOINT ["pdfcraft"]docker build -t pdfcraft .
docker run --rm -v $(pwd):/data pdfcraft merge /data/a.pdf /data/b.pdf -o /data/merged.pdf我们欢迎任何形式的贡献！无论是提交 Bug、改进文档，还是贡献代码。
- Fork 本仓库
- 创建特性分支：
git checkout -b feature/your-feature - 提交更改：
git commit -m "feat: add your feature" - 推送分支：
git push origin feature/your-feature - 提交 Pull Request
git clone https://github.com/your-org/pdfcraft.git
cd pdfcraft
pip install -e ".[dev]"- 遵循 PEP 8 编码规范
- 使用 Black 格式化代码
- 使用 Ruff 进行 lint 检查
- 编写单元测试，确保通过所有 CI 检查
使用 Conventional Commits 格式：
feat: 新增 PDF 合并功能
fix: 修复大文件拆分时的内存溢出问题
docs: 更新 README 文档
refactor: 重构压缩模块
本项目基于 MIT License 开源。
MIT License
Copyright (c) 2025 PDFCraft Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
Made with ❤️ by PDFCraft Contributors
一站式 PDF 處理解決方案，16 項核心功能，完全本地運行，無需上傳檔案到雲端。
在日常辦公和學習中，PDF 檔案的處理幾乎無處不在——合併報告、拆分合約、新增浮水印、壓縮檔案體積……然而市面上大多數 PDF 工具要麼功能臃腫、收費高昂，要麼需要將檔案上傳到雲端，存在隱私洩露的風險。
PDFCraft 正是為了解決這些痛點而誕生的：
| 痛點 | PDFCraft 的解決方案 |
|---|---|
| 雲端工具隱私風險 | 完全本地處理，檔案不離開你的電腦 |
| 線上工具收費昂貴 | 開源免費，MIT 協議，無任何限制 |
| 功能分散在多個工具 | 16 合 1，一個工具覆蓋所有常見需求 |
| 命令列工具門檻高 | 提供 CLI + TUI + GUI 三種互動方式 |
| 安裝配置複雜 | 一條命令安裝，開箱即用 |
核心定位：輕量、快速、安全、易用。不追求大而全，而是把每一項功能做到極致。
PDFCraft 提供 16 項核心功能，覆蓋 PDF 處理的方方面面：
| 序號 | 功能 | 說明 |
|---|---|---|
| 1 | 📎 PDF 合併 | 多檔案智慧合併，自動產生目錄書籤 |
| 2 | ✂️ PDF 拆分 | 按頁碼、範圍或章節靈活拆分 |
| 3 | 🖼️ PDF 轉圖片 | 高畫質 PNG/JPG 匯出，自訂 DPI |
| 4 | 📸 圖片轉 PDF | 批量圖片智慧合成 PDF 文件 |
| 5 | 🗜️ PDF 壓縮 | 智慧壓縮演算法，在體積與品質間取得平衡 |
| 6 | 💧 浮水印新增 | 支援文字/圖片浮水印，自訂位置與透明度 |
| 7 | 🔒 PDF 加密 | AES-256 強加密，密碼保護你的文件 |
| 8 | 🔓 PDF 解密 | 快速移除 PDF 密碼保護 |
| 9 | 🔄 頁面旋轉 | 精確到每一頁的旋轉控制 |
| 10 | ✂️ 頁面裁切 | 精確到毫米的頁面裁切 |
| 11 | ℹ️ 元資料檢視 | 一鍵檢視 PDF 文件詳細資訊 |
| 12 | ✏️ 元資料編輯 | 修改標題、作者、關鍵字等元資訊 |
| 13 | 📝 文字擷取 | 高精度擷取 PDF 中的文字內容 |
| 14 | 🖼️ 圖片擷取 | 擷取 PDF 中嵌入的所有圖片 |
| 15 | ⚡ 批量處理 | 多檔案平行處理，效率翻倍 |
| 16 | 🖥️ TUI 互動介面 | 終端中的視覺化選單，告別記命令 |
- Python >= 3.8
- 作業系統：Windows / macOS / Linux
# 從 PyPI 安裝（推薦）
pip install pdfcraft
# 或從原始碼開發模式安裝
git clone https://github.com/your-org/pdfcraft.git
cd pdfcraft
pip install -e .pdfcraft --version
# 輸出: pdfcraft, version 1.0.0
pdfcraft --help
# 檢視所有可用命令# 1. 命令列模式（CLI）—— 適合腳本和自動化
pdfcraft merge file1.pdf file2.pdf -o merged.pdf
# 2. 終端互動模式（TUI）—— 適合日常使用
pdfcraft tui
# 3. 圖形介面模式（GUI）—— 適合非技術使用者
pdfcraft gui將多個 PDF 檔案合併為一個，支援自動產生目錄書籤。
# 基本合併
pdfcraft merge file1.pdf file2.pdf file3.pdf -o merged.pdf
# 合併整個目錄下的 PDF
pdfcraft merge ./reports/*.pdf -o all-reports.pdf
# 合併並產生書籤（以檔案名稱作為書籤）
pdfcraft merge file1.pdf file2.pdf -o merged.pdf --bookmarks按頁碼、範圍或章節靈活拆分 PDF。
# 按頁碼範圍拆分
pdfcraft split input.pdf -r "1-3,5,7-10" -o output_dir/
# 每隔 N 頁拆分
pdfcraft split input.pdf -n 5 -o output_dir/
# 拆分為單頁
pdfcraft split input.pdf --each -o output_dir/將 PDF 頁面匯出為高畫質圖片。
# 匯出為 PNG，預設 150 DPI
pdfcraft pdf2img input.pdf -o images/
# 自訂 DPI 和格式
pdfcraft pdf2img input.pdf -o images/ --dpi 300 --format jpg
# 僅匯出指定頁面
pdfcraft pdf2img input.pdf -o images/ -r "1,3,5-8"將多張圖片合併為一個 PDF 文件。
# 基本轉換
pdfcraft img2pdf img1.png img2.jpg img3.png -o output.pdf
# 批量轉換目錄下的圖片
pdfcraft img2pdf ./photos/*.jpg -o album.pdf
# 自訂頁面尺寸
pdfcraft img2pdf img1.png img2.png -o output.pdf --pagesize A4智慧壓縮 PDF 檔案，在體積和品質之間取得最佳平衡。
# 預設壓縮（品質因子 0.7）
pdfcraft compress input.pdf -o compressed.pdf
# 指定壓縮品質（0.0 ~ 1.0，越小體積越小）
pdfcraft compress input.pdf -o compressed.pdf -q 0.5
# 極限壓縮（體積最小）
pdfcraft compress input.pdf -o compressed.pdf -q 0.3為 PDF 新增文字或圖片浮水印。
# 新增文字浮水印
pdfcraft watermark input.pdf -o watermarked.pdf -t "CONFIDENTIAL"
# 自訂浮水印樣式
pdfcraft watermark input.pdf -o watermarked.pdf \
-t "內部檔案" \
--opacity 0.3 \
--angle 45 \
--fontsize 60 \
--color "#FF0000"
# 新增圖片浮水印
pdfcraft watermark input.pdf -o watermarked.pdf \
--image logo.png \
--opacity 0.2使用 AES-256 演算法為 PDF 新增密碼保護。
# 基本加密
pdfcraft encrypt input.pdf -o encrypted.pdf -p mypassword
# 設定權限（禁止列印/複製/編輯）
pdfcraft encrypt input.pdf -o encrypted.pdf -p mypassword \
--no-print --no-copy --no-edit移除 PDF 的密碼保護。
pdfcraft decrypt encrypted.pdf -o decrypted.pdf -p mypassword精確旋轉 PDF 的指定頁面。
# 所有頁面旋轉 90 度
pdfcraft rotate input.pdf -o rotated.pdf --angle 90
# 僅旋轉指定頁面
pdfcraft rotate input.pdf -o rotated.pdf -r "1,3,5" --angle 180精確裁切 PDF 頁面。
# 按邊距裁切（單位：毫米）
pdfcraft crop input.pdf -o cropped.pdf \
--left 20 --right 20 --top 30 --bottom 30
# 按比例裁切
pdfcraft crop input.pdf -o cropped.pdf --ratio 0.9檢視 PDF 文件的詳細元資訊。
pdfcraft info input.pdf
# 輸出示例：
# 檔案名稱: input.pdf
# 頁數: 42
# 標題: Annual Report 2025
# 作者: PDFCraft Team
# 建立時間: 2025-01-15 10:30:00
# 檔案大小: 3.2 MB
# PDF版本: 1.7修改 PDF 的元資料資訊。
pdfcraft metadata input.pdf -o output.pdf \
--title "年度報告 2025" \
--author "張三" \
--subject "財務報告" \
--keywords "年報,財務,2025"高精度擷取 PDF 中的文字內容。
# 擷取全部文字
pdfcraft extract-text input.pdf -o output.txt
# 擷取指定頁面
pdfcraft extract-text input.pdf -o output.txt -r "1-5"
# 輸出為 Markdown 格式
pdfcraft extract-text input.pdf -o output.md --format markdown擷取 PDF 中嵌入的所有圖片。
# 擷取所有圖片
pdfcraft extract-images input.pdf -o images/
# 僅擷取指定頁面的圖片
pdfcraft extract-images input.pdf -o images/ -r "3-10"
# 指定輸出格式
pdfcraft extract-images input.pdf -o images/ --format png對多個檔案執行相同操作，支援平行處理。
# 批量壓縮
pdfcraft batch compress ./reports/*.pdf -o ./compressed/ --parallel 4
# 批量新增浮水印
pdfcraft batch watermark ./contracts/*.pdf -o ./watermarked/ -t "機密"
# 批量加密
pdfcraft batch encrypt ./docs/*.pdf -o ./encrypted/ -p mypassword啟動終端互動式選單，無需記憶任何命令。
pdfcraft tui啟動後，你將看到一個視覺化的功能選單，透過方向鍵選擇、Enter 確認即可完成操作。適合日常使用和不熟悉命令列的使用者。
- 本地優先：所有處理在本地完成，檔案零上傳，隱私零風險
- 模組化架構：每個功能獨立模組，按需載入，啟動迅速
- 漸進式互動：CLI 適合自動化，TUI 適合互動式使用，GUI 適合圖形化操作
- 零外部依賴：核心功能不依賴任何線上服務，離線可用
| 元件 | 技術 | 用途 |
|---|---|---|
| PDF 引擎 | PyMuPDF (fitz) | 高效能 PDF 讀寫 |
| CLI 框架 | Click | 命令列介面建構 |
| 終端美化 | Rich | 彩色輸出、進度條、表格 |
| 互動介面 | Prompt Toolkit | TUI 終端互動 |
| 圖形介面 | Tkinter | GUI 圖形介面 |
- v1.0.0 — 16 項核心功能，CLI + TUI + GUI
- v1.1.0 — OCR 文字辨識，支援掃描件 PDF
- v1.2.0 — PDF 表單填寫與建立
- v2.0.0 — PDF 編輯（插入/刪除頁面，新增標註）
- v2.1.0 — 外掛系統，支援第三方功能擴充
- v3.0.0 — Web UI，在瀏覽器中操作 PDF
# 安裝建構工具
pip install build
# 建構
python -m build
# 產物在 dist/ 目錄下
ls dist/
# pdfcraft-1.0.0-py3-none-any.whl
# pdfcraft-1.0.0.tar.gz# 安裝 Twine
pip install twine
# 上傳
twine upload dist/*# 安裝 PyInstaller
pip install pyinstaller
# 打包為單檔案
pyinstaller --onefile --name pdfcraft src/pdfcraft/main.py
# 產物在 dist/pdfcraft（或 dist/pdfcraft.exe）FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -e .
ENTRYPOINT ["pdfcraft"]docker build -t pdfcraft .
docker run --rm -v $(pwd):/data pdfcraft merge /data/a.pdf /data/b.pdf -o /data/merged.pdf我們歡迎任何形式的貢獻！無論是提交 Bug、改進文件，還是貢獻程式碼。
- Fork 本儲存庫
- 建立特性分支：
git checkout -b feature/your-feature - 提交變更：
git commit -m "feat: add your feature" - 推送分支：
git push origin feature/your-feature - 提交 Pull Request
git clone https://github.com/your-org/pdfcraft.git
cd pdfcraft
pip install -e ".[dev]"- 遵循 PEP 8 編碼規範
- 使用 Black 格式化程式碼
- 使用 Ruff 進行 lint 檢查
- 撰寫單元測試，確保通過所有 CI 檢查
使用 Conventional Commits 格式：
feat: 新增 PDF 合併功能
fix: 修復大檔案拆分時的記憶體溢出問題
docs: 更新 README 文件
refactor: 重構壓縮模組
本專案基於 MIT License 開源。
MIT License
Copyright (c) 2025 PDFCraft Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
Made with ❤️ by PDFCraft Contributors
An all-in-one PDF processing solution with 16 core features. Runs entirely on your local machine — no cloud uploads required.
- Project Introduction
- Core Features
- Quick Start
- Detailed Usage Guide
- Design Philosophy & Roadmap
- Build & Deploy Guide
- Contributing Guide
- License
PDF files are everywhere — merging reports, splitting contracts, adding watermarks, compressing file sizes. Yet most PDF tools on the market are either bloated and expensive, or they require uploading your files to the cloud, raising serious privacy concerns.
PDFCraft was built to solve exactly these problems:
| Pain Point | PDFCraft's Solution |
|---|---|
| Cloud tools risk your privacy | 100% local processing — your files never leave your machine |
| Online tools are expensive | Free & open-source under the MIT license |
| Features scattered across tools | 16-in-1 — one tool for all your PDF needs |
| CLI tools have a steep learning curve | CLI + TUI + GUI — three ways to interact |
| Complex setup and installation | One command to install, ready to use out of the box |
Core philosophy: Lightweight, fast, secure, and easy to use. Rather than trying to do everything, we focus on making each feature truly excellent.
PDFCraft ships with 16 core features covering every aspect of PDF processing:
| # | Feature | Description |
|---|---|---|
| 1 | 📎 Merge | Intelligently merge multiple PDFs with auto-generated bookmarks |
| 2 | ✂️ Split | Split by page number, range, or chapter |
| 3 | 🖼️ PDF to Images | Export as high-res PNG/JPG with custom DPI |
| 4 | 📸 Images to PDF | Combine multiple images into a single PDF |
| 5 | 🗜️ Compress | Smart compression that balances file size and quality |
| 6 | 💧 Watermark | Add text or image watermarks with custom position and opacity |
| 7 | 🔒 Encrypt | AES-256 encryption to password-protect your documents |
| 8 | 🔓 Decrypt | Quickly remove password protection from PDFs |
| 9 | 🔄 Rotate | Precise per-page rotation control |
| 10 | ✂️ Crop | Precise page cropping down to the millimeter |
| 11 | ℹ️ Info | View detailed PDF metadata at a glance |
| 12 | ✏️ Metadata | Edit title, author, keywords, and more |
| 13 | 📝 Extract Text | High-accuracy text extraction from PDFs |
| 14 | 🖼️ Extract Images | Extract all embedded images from a PDF |
| 15 | ⚡ Batch | Process multiple files in parallel |
| 16 | 🖥️ TUI | Interactive terminal menu — no need to memorize commands |
- Python >= 3.8
- OS: Windows / macOS / Linux
# Install from PyPI (recommended)
pip install pdfcraft
# Or install from source in development mode
git clone https://github.com/your-org/pdfcraft.git
cd pdfcraft
pip install -e .pdfcraft --version
# Output: pdfcraft, version 1.0.0
pdfcraft --help
# View all available commands# 1. Command-line mode (CLI) — great for scripts and automation
pdfcraft merge file1.pdf file2.pdf -o merged.pdf
# 2. Terminal interactive mode (TUI) — great for daily use
pdfcraft tui
# 3. Graphical interface mode (GUI) — great for non-technical users
pdfcraft guiCombine multiple PDF files into one, with optional auto-generated bookmarks.
# Basic merge
pdfcraft merge file1.pdf file2.pdf file3.pdf -o merged.pdf
# Merge all PDFs in a directory
pdfcraft merge ./reports/*.pdf -o all-reports.pdf
# Merge with bookmarks (uses filenames as bookmark labels)
pdfcraft merge file1.pdf file2.pdf -o merged.pdf --bookmarksSplit a PDF by page number, range, or at fixed intervals.
# Split by page range
pdfcraft split input.pdf -r "1-3,5,7-10" -o output_dir/
# Split every N pages
pdfcraft split input.pdf -n 5 -o output_dir/
# Split into individual pages
pdfcraft split input.pdf --each -o output_dir/Export PDF pages as high-resolution images.
# Export as PNG at default 150 DPI
pdfcraft pdf2img input.pdf -o images/
# Custom DPI and format
pdfcraft pdf2img input.pdf -o images/ --dpi 300 --format jpg
# Export specific pages only
pdfcraft pdf2img input.pdf -o images/ -r "1,3,5-8"Combine multiple images into a single PDF document.
# Basic conversion
pdfcraft img2pdf img1.png img2.jpg img3.png -o output.pdf
# Batch convert all images in a directory
pdfcraft img2pdf ./photos/*.jpg -o album.pdf
# Custom page size
pdfcraft img2pdf img1.png img2.png -o output.pdf --pagesize A4Intelligently compress PDF files while preserving quality.
# Default compression (quality factor 0.7)
pdfcraft compress input.pdf -o compressed.pdf
# Specify quality (0.0 ~ 1.0, lower = smaller file)
pdfcraft compress input.pdf -o compressed.pdf -q 0.5
# Maximum compression (smallest file size)
pdfcraft compress input.pdf -o compressed.pdf -q 0.3Add text or image watermarks to your PDFs.
# Add a text watermark
pdfcraft watermark input.pdf -o watermarked.pdf -t "CONFIDENTIAL"
# Customize watermark appearance
pdfcraft watermark input.pdf -o watermarked.pdf \
-t "INTERNAL" \
--opacity 0.3 \
--angle 45 \
--fontsize 60 \
--color "#FF0000"
# Add an image watermark
pdfcraft watermark input.pdf -o watermarked.pdf \
--image logo.png \
--opacity 0.2Protect your PDFs with AES-256 encryption.
# Basic encryption
pdfcraft encrypt input.pdf -o encrypted.pdf -p mypassword
# Set permissions (disable printing, copying, editing)
pdfcraft encrypt input.pdf -o encrypted.pdf -p mypassword \
--no-print --no-copy --no-editRemove password protection from a PDF.
pdfcraft decrypt encrypted.pdf -o decrypted.pdf -p mypasswordRotate specific pages of a PDF with precision.
# Rotate all pages by 90 degrees
pdfcraft rotate input.pdf -o rotated.pdf --angle 90
# Rotate only specific pages
pdfcraft rotate input.pdf -o rotated.pdf -r "1,3,5" --angle 180Crop PDF pages with millimeter-level precision.
# Crop by margins (in millimeters)
pdfcraft crop input.pdf -o cropped.pdf \
--left 20 --right 20 --top 30 --bottom 30
# Crop by ratio
pdfcraft crop input.pdf -o cropped.pdf --ratio 0.9View detailed metadata of a PDF document.
pdfcraft info input.pdf
# Example output:
# Filename: input.pdf
# Pages: 42
# Title: Annual Report 2025
# Author: PDFCraft Team
# Created: 2025-01-15 10:30:00
# File size: 3.2 MB
# PDF version: 1.7Edit the metadata of a PDF document.
pdfcraft metadata input.pdf -o output.pdf \
--title "Annual Report 2025" \
--author "John Doe" \
--subject "Financial Report" \
--keywords "annual,finance,2025"Extract text content from PDFs with high accuracy.
# Extract all text
pdfcraft extract-text input.pdf -o output.txt
# Extract from specific pages
pdfcraft extract-text input.pdf -o output.txt -r "1-5"
# Output as Markdown
pdfcraft extract-text input.pdf -o output.md --format markdownExtract all images embedded in a PDF.
# Extract all images
pdfcraft extract-images input.pdf -o images/
# Extract from specific pages only
pdfcraft extract-images input.pdf -o images/ -r "3-10"
# Specify output format
pdfcraft extract-images input.pdf -o images/ --format pngApply the same operation to multiple files with parallel processing support.
# Batch compress
pdfcraft batch compress ./reports/*.pdf -o ./compressed/ --parallel 4
# Batch watermark
pdfcraft batch watermark ./contracts/*.pdf -o ./watermarked/ -t "CONFIDENTIAL"
# Batch encrypt
pdfcraft batch encrypt ./docs/*.pdf -o ./encrypted/ -p mypasswordLaunch the interactive terminal menu — no commands to memorize.
pdfcraft tuiOnce launched, you'll see a visual feature menu. Navigate with arrow keys and press Enter to confirm. Perfect for everyday use and users who prefer not to use the command line.
- Local-first: All processing happens on your machine. Zero uploads, zero privacy risks.
- Modular architecture: Each feature is an independent module, loaded on demand for fast startup.
- Progressive interaction: CLI for automation, TUI for interactive use, GUI for visual workflows.
- Zero cloud dependency: Core features work entirely offline — no internet required.
| Component | Technology | Purpose |
|---|---|---|
| PDF Engine | PyMuPDF (fitz) | High-performance PDF reading and writing |
| CLI Framework | Click | Command-line interface construction |
| Terminal UI | Rich | Colored output, progress bars, tables |
| Interactive UI | Prompt Toolkit | TUI terminal interaction |
| Graphical UI | Tkinter | GUI graphical interface |
- v1.0.0 — 16 core features, CLI + TUI + GUI
- v1.1.0 — OCR text recognition for scanned PDFs
- v1.2.0 — PDF form filling and creation
- v2.0.0 — PDF editing (insert/delete pages, add annotations)
- v2.1.0 — Plugin system for third-party extensions
- v3.0.0 — Web UI for browser-based PDF operations
# Install build tools
pip install build
# Build
python -m build
# Output is in the dist/ directory
ls dist/
# pdfcraft-1.0.0-py3-none-any.whl
# pdfcraft-1.0.0.tar.gz# Install Twine
pip install twine
# Upload
twine upload dist/*# Install PyInstaller
pip install pyinstaller
# Build as a single-file executable
pyinstaller --onefile --name pdfcraft src/pdfcraft/main.py
# Output: dist/pdfcraft (or dist/pdfcraft.exe on Windows)FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -e .
ENTRYPOINT ["pdfcraft"]docker build -t pdfcraft .
docker run --rm -v $(pwd):/data pdfcraft merge /data/a.pdf /data/b.pdf -o /data/merged.pdfWe welcome contributions of all kinds — bug reports, documentation improvements, or code contributions.
- Fork this repository
- Create a feature branch:
git checkout -b feature/your-feature - Commit your changes:
git commit -m "feat: add your feature" - Push the branch:
git push origin feature/your-feature - Submit a Pull Request
git clone https://github.com/your-org/pdfcraft.git
cd pdfcraft
pip install -e ".[dev]"- Follow PEP 8 coding conventions
- Use Black for code formatting
- Use Ruff for linting
- Write unit tests and ensure all CI checks pass
Follow the Conventional Commits specification:
feat: add PDF merge feature
fix: resolve memory overflow when splitting large files
docs: update README documentation
refactor: restructure compression module
This project is licensed under the MIT License.
MIT License
Copyright (c) 2025 PDFCraft Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
Made with ❤️ by PDFCraft Contributors