A beautifully crafted, terminal-native PDF compressor — built in pure Rust.
Features · Installation · Usage · Architecture · Tech Stack · Roadmap · Contributing · License
tuipdf brings production-grade PDF optimization directly into your terminal. It delivers a rich, keyboard-driven TUI experience with zero external C dependencies and zero third-party tool licenses to worry about.
No uploads. No cloud. No tracking. Your files never leave your machine.
Built for developers, power users, and open-source contributors who believe productivity tools should be fast, local, and beautiful.
The pipeline is implemented in pure Rust with a color-space-aware, per-object compression strategy:
| Input Type | Strategy |
|---|---|
| JPEG images | Decoded, optionally DPI downsampled, and re-encoded at target quality. |
| FlateDecode (PNG-style) | Decompressed, color-space-aware pixel reconstruction, converted to JPEG. |
| Grayscale / 1-bit B&W | Preserved as grayscale JPEG — eliminates unnecessary channel bloat. |
| CMYK images | Converted to RGB via standard subtractive model before encoding. |
| Indexed / Separation / DeviceN | Safely skipped to prevent discoloration. |
| Content streams, fonts, vectors | Kept intact — never recompressed. |
| Feature | Description | |
|---|---|---|
| 📦 | Smart Compression | Deep, per-object PDF analysis — images are aggressively compressed while vectors and text remain crystal clear. |
| 🎚️ | Tailored Profiles | Three optimized tiers: Low (85% quality), Medium (75%), and High (50% + metadata stripping). |
| 🎨 | Color Fidelity | Full detection of DeviceRGB, DeviceGray, DeviceCMYK, and ICCBased color spaces prevents discoloration. |
| 📄 | Scanned PDF Support | Handles B&W, grayscale, and color documents at 1-bit, 2-bit, 4-bit, and 8-bit depths. |
| 🖥️ | Beautiful TUI | A slick, distraction-free terminal interface with smooth animations and real-time processing stats. |
| 🔒 | Privacy First | 100% local, offline processing. Zero data collection. |
| ⚡ | Blazing Fast | Pure Rust with rayon for data-parallel processing and automatic memory-pressure detection. |
| 🔧 | Zero C Dependencies | No system libraries, no CMake, no MuPDF — everything builds from source via cargo. |
For full prerequisites, platform-specific instructions, troubleshooting, and manual compilation steps, see the Installation Guide.
Cargo (crates.io):
cargo install tuipdfWindows (PowerShell):
irm https://raw.githubusercontent.com/KnightShadows/tuipdf/main/install_windows.ps1 | iexLinux (Debian / Ubuntu):
git clone https://github.com/KnightShadows/tuipdf.git && cd tuipdf
./install.shmacOS:
git clone https://github.com/KnightShadows/tuipdf.git && cd tuipdf
./install_mac.shFrom Source (any platform):
git clone https://github.com/KnightShadows/tuipdf.git && cd tuipdf
cargo install --path .Launch the interactive terminal interface:
tuipdfOpen a PDF directly:
tuipdf path/to/document.pdf| Shortcut | Action |
|---|---|
Enter |
Cycle compression levels / Start compression |
Tab |
Switch UI focus |
q / Esc |
Gracefully quit |
Ctrl+C |
Force quit |
┌──────────┐ ┌───────────┐ ┌──────────────┐ ┌───────────┐ ┌──────────┐
│ Load & │────▶│ Classify │────▶│ Extract & │────▶│ Rebuild & │────▶│ Write │
│ Parse │ │ Objects │ │ Compress │ │ Reinsert │ │ Output │
└──────────┘ └───────────┘ └──────────────┘ └───────────┘ └──────────┘
│ │ │ │ │
lopdf Color space image crate Update Export
parser detection JPEG encoding dictionaries final PDF
- Parse —
lopdfloads and validates the PDF structure. - Classify — Each stream object is tagged: JPEG, PNG/Flate, RawBitmap, Font, FormXObject, or Content Stream.
- Color Detect — The
ColorSpacedictionary entry is fully resolved (DeviceRGB, DeviceCMYK, ICCBased N=?, Indexed → skip). - Extract — Streams are decompressed to raw pixel bytes.
- Compress — Images are re-encoded as JPEG at target quality; content streams and fonts are untouched.
- Rebuild — Compressed data is reinserted with updated dictionary entries (Filter, Width, Height, ColorSpace, BitsPerComponent).
- Write — The document is saved with standard cross-reference tables.
| tuipdf | Online Compressors | |
|---|---|---|
| 🔒 Privacy | ✅ Files stay strictly local | ❌ Uploaded to remote servers |
| ⚡ Speed | ✅ Instant, native execution | ❌ Bottlenecked by connection |
| 🌐 Offline | ✅ Always works | ❌ Requires internet |
| 💸 Cost | ✅ Free, forever | ❌ Often paywalled or limited |
| 🖥️ Workflow | ✅ Stays in your terminal | ❌ Context-switch to browser |
| 📄 Scanned PDFs | ✅ Full multi-depth support | |
| 🎨 Color Fidelity | ✅ CMYK / ICC aware |
| Component | Role |
|---|---|
| ratatui | Rich, responsive TUI framework |
| crossterm | Cross-platform terminal backend |
| lopdf | Low-level PDF parsing and manipulation |
| image | High-performance image decoding and encoding |
| flate2 | Fast Zlib compression for FlateDecode streams |
| rayon | Fearless data-parallel concurrency |
- Pure-Rust compression pipeline with full color-space awareness
- Scanned PDF support and intelligent memory-pressure detection
- Premium TUI with dynamic gradients and active animations
- Robust cross-platform build (Windows, Linux, macOS)
- Tailored compression tiers (Low, Medium, High)
- Comprehensive integration test suite
- PDF to Image / Image to PDF
- PDF to Word / Word to PDF
- Merge and Split operations
- Page Extraction and Removal
- Add / Remove PDF Passwords
- Batch Processing Mode
- Integrated terminal-native file picker
Open source is built on collaboration. Whether it's a bug report, a new feature, or a documentation improvement — your contributions are highly valued.
Please review the Contribution Guidelines before getting started.
Copyright © 2026 KnightShadows Organization & Aditya Anand
This project is licensed under the Mozilla Public License 2.0 (MPL 2.0).