A PDF reader and editor built with C++23, Qt 6, QML, and PDFium.
Beta: TrePDF is under active development. Features, PDF compatibility, and the interface are still evolving. Keep your original documents and use Save As on a copy when testing edits. Bug reports and contributions are welcome.
TrePDF lets you read, edit, annotate, fill forms, and convert PDFs on your own computer. Document processing runs locally. Optional font and OCR-language downloads require an internet connection; they do not upload your PDF.
Build from source · Contribute · Report a bug · Source documentation
| Area | Current desktop capabilities |
|---|---|
| Read | Multiple document tabs, thumbnails, search, text selection, zoom, rotation, facing pages, and split views. |
| Edit | Edit supported existing text, add text and images, draw shapes, create tables, and edit their cells. |
| Annotate | Notes, highlights, free text, drawing comments, stamps, replies, and review statuses. |
| Forms and signatures | Fill supported AcroForms, create form fields, and place visible signatures, initials, and dates. |
| Organize | Insert/delete pages, merge PDFs, and split a PDF into separate files. |
| Headers and footers | Add text, images, and page numbers, with page ranges and synchronization for supported objects. |
| Protect | Add or change an opening password on eligible PDFs; add, update, or remove managed watermarks. |
| Convert | Recognize scanned text with local OCR and export supported ruled tables to Excel (.xlsx). |
Edits are staged as document drafts with Undo/Redo and Discard. Save and Save As persist supported changes and reopen the result. Each document tab keeps its own editing history and view state.
- PDF editing depends on the document's fonts and structure. Complex or unsupported objects remain read-only; this is not a guarantee that every PDF can be edited without layout changes.
- Excel export requires text-based tables with supported ruled grids. Borderless tables and image-only scans are not supported by the table extractor.
- Visible signatures are images, not certificate-based digital signatures.
- Some encrypted-document edits and advanced AcroForm structures are unsupported. See the relevant pipeline document before changing these behaviors.
- Desktop PDF JavaScript is enabled for form behavior, with restricted host actions. PDFium has no hard execution timeout for synchronous scripts.
The repository includes these build paths. A build recipe does not imply that every feature has been verified on every platform.
| Platform | Build path |
|---|---|
| macOS, Apple Silicon | Bundled ARM64 dependencies, local CMake build, and the uat workflow. |
| macOS, Intel | Native dependency preparation and the separate uat-macos-intel workflow. |
| Windows x64 | Local MSVC packaging script and the uat workflow; a separate MinGW setup guide is available. |
| Linux x64 | Ubuntu 24.04 build and packaging recipe in the uat workflow. |
| iPad | Separate iOS build and uat-ipad workflow; see the iPad guide. |
| Browser | Separate WebAssembly preview with a smaller feature set; see the web guide. |
macOS packages are separate for ARM64 (M1 and newer) and Intel; they are not universal binaries. The current desktop workflows configure Qt 6.12 packages for macOS 14.4+, with Qt 6.11 variants targeting macOS 13+. The Qt 6.8.3 compatibility variants target macOS 12+ on both architectures, using a separate PDFium pin and native dependency builds. They need UAT on macOS 12; the GitHub runners use macOS 15.
For test packages, follow the manual UAT guide. It explains
how to run a workflow and download its artifacts. Each macOS job provides a
direct-download .dmg artifact and a separate .dmg.sha256 artifact, plus a
ZIP fallback. The DMG opens with the app on the left and an arrow pointing to
Applications on the right; drag the app across to install it. These workflows
do not publish GitHub Releases or run the full feature test suite. Current
macOS test packages use ad-hoc signing and are not notarized.
- Git, CMake 3.21+, and a C++23-capable compiler and standard library.
- A matching Qt 6.8+ desktop kit with QML, Quick, Quick Controls 2, Network, and LinguistTools. Install Qt Test for tests and Qt Svg for runtime deployment. The current desktop workflows use Qt 6.12.0, plus Qt 6.11.0 macOS variants, and compatibility builds with Qt 6.8.3; their module lists are in the workflow files.
- Ninja for the commands below.
- Native PDFium, qpdf, Tesseract/Leptonica, and zlib dependencies matching your operating system and architecture. libxlsxwriter is built from vendored source.
- Python 3.12+ if using the dependency preparation or local packaging scripts.
The checked-in PDFium, qpdf, and OCR binaries are macOS ARM64 packages. They cannot be reused for Intel, Windows, Linux, iOS, or WebAssembly builds. Normal desktop CMake configuration does not download missing dependencies.
git clone https://github.com/RaymondHuy/TrePDF.git
cd TrePDFFor contributions, clone your fork instead. Run the following commands from the repository root.
Install Xcode's command-line tools and a compatible Qt macOS kit first. Adjust
TREPDF_QT_PREFIX to your own installation; CLion is optional.
TREPDF_QT_PREFIX="$HOME/Qt/6.12.0/macos"
cmake -S . -B build -G Ninja \
-DCMAKE_BUILD_TYPE=Debug \
-DCMAKE_OSX_ARCHITECTURES=arm64 \
-DBUILD_TESTING=ON \
-DTREPDF_DEPLOY_RUNTIME=OFF \
-DQt6_DIR="$TREPDF_QT_PREFIX/lib/cmake/Qt6" \
-DCMAKE_PREFIX_PATH="$TREPDF_QT_PREFIX" \
-DPDFium_ROOT="$PWD/third_party/pdfium" \
-DQPDF_ROOT="$PWD/third_party/qpdf" \
-DOCR_ROOT="$PWD/third_party/ocr"
cmake --build build --target trepdf --parallel 4
./build/trepdf.app/Contents/MacOS/trepdfRe-run the build command after editing source. Use a separate build directory
when changing the compiler, architecture, or Qt kit. For an optimized .app
or a drag-to-install .dmg, see the local macOS Release guide.
The local scripts use installed tools and prepare native dependencies. Windows produces a runnable Release application folder; macOS creates a Release ZIP with a checksum. The first run needs network access for pinned dependency downloads. The check commands below validate local tools without downloading dependencies or building the app.
macOS ARM64 or Intel — run natively on the target architecture with Qt, Python 3.12+, CMake, Ninja, and Xcode tools installed:
bash pipelines/build-macos.sh --qt "$HOME/Qt/6.12.0/macos" --check
bash pipelines/build-macos.sh --qt "$HOME/Qt/6.12.0/macos"Windows x64 — use 64-bit PowerShell, Visual Studio C++ tools with a Windows SDK, a Qt MSVC x64 kit, Python 3.12+, CMake, and Ninja. Replace the example Qt path:
.\pipelines\build-windows.ps1 -QtRoot 'C:\Qt\6.12.0\msvc2022_64' -CheckOnly
.\pipelines\build-windows.ps1 -QtRoot 'C:\Qt\6.12.0\msvc2022_64'Windows output is artifacts/local/windows-x64/TrePDF-<version>-windows-x64/.
Run bin/trepdf.exe inside it and keep the entire folder together with its
deployed libraries and resources. The Windows script creates no ZIP or archive
checksum. macOS packages remain under artifacts/local/<platform>/.
These scripts build Release applications with tests disabled. For Linux or custom
toolchains, use the
dependency preparation and configure steps in the UAT workflow.
Pass the prepared PDFium_ROOT, QPDF_ROOT, and OCR_ROOT explicitly to CMake.
The UAT guide describes platform requirements and outputs;
the Windows CLion guide covers the separate MinGW setup.
Open the repository as a CMake project, select your installed compiler and Qt
kit, and use the same CMake options as the development build above. Run the
trepdf target. Do not copy another developer's CMake cache or absolute SDK paths.
With the development build configured using BUILD_TESTING=ON, build the test
targets and run CTest. This example uses the bundled Apple Silicon libraries:
cmake --build build --parallel 4
DYLD_LIBRARY_PATH="$PWD/third_party/pdfium/lib:$PWD/third_party/qpdf/lib" \
QT_QPA_PLATFORM=offscreen QT_QUICK_BACKEND=software \
ctest --test-dir build --output-on-failureFor other platforms, use their native dependency/runtime paths. See the test guide for individual Qt Test methods and fixture conventions. Offscreen tests do not replace native UI checks, especially for macOS Metal rendering. The contribution guide explains which checks to run for each kind of change.
| Location | Purpose |
|---|---|
src/main.cpp, src/Main.qml |
Desktop startup and application composition. |
src/Components/ |
QML interface, document views, tools, and editing overlays. |
src/PDFDocumentSession.*, src/PDFTabModel.* |
Per-document state and document tabs. |
src/PDFEditController*.cpp |
Selection, drafts, editing commands, and history. |
src/PDFSaveWriter.cpp |
Validating and writing PDF content changes. |
src/PDFPageItem.*, src/PDFFormWorker.* |
Page rendering and worker-owned PDF/form interaction. |
src/web/, src/ios/, src/platform/ |
Browser preview and native platform integrations. |
i18n/ |
Qt translation catalogs. |
tests/ |
Qt tests and reproducible fixtures. |
cmake/, pipelines/, scripts/ci/, .github/workflows/ |
Dependency discovery, builds, and packaging. |
third_party/ |
Bundled dependencies and their notices. |
QML presents the interface; C++ controllers own document state and operations. Workers perform rendering and longer PDF tasks using their own handles. Edits remain drafts until the save pipeline validates and commits them. Preserve these boundaries when adding features; see Contributing.
The desktop UI defaults to Vietnamese. Choose Settings → Language to switch
between Tiếng Việt, English, Hrvatski, ไทย, Français,
Deutsch, Español, Português (Brasil), 日本語, 简体中文,
한국어, and Bahasa Indonesia immediately. TrePDF remembers the selection
for the next launch; no rebuild or download is needed.
All twelve catalogs are bundled from i18n/qml_<locale>.ts. See
UI language settings.
Use Qt's ID-based translations: qsTrId() in QML and qtTrId() in C++, with
stable PascalCase IDs and English source comments. After changing UI strings:
cmake --build build --target update_translations
# Complete the affected translation entries before rebuilding.
cmake --build build --target trepdf trepdf_qmllint --parallel 4To add a language, register it in I18N_TRANSLATED_LANGUAGES in
CMakeLists.txt, generate and translate its catalog, and add the locale to
src/ApplicationLanguage.h and src/Components/LanguageMenuButton.qml.
Preserve placeholders such as %1 and %n. See the
translation contribution guide.
New contributors can help with reproducible bug reports, PDF compatibility tests, translations, accessibility, documentation, and platform testing as well as code. Small, focused improvements are welcome.
Read CONTRIBUTING.md for setup, coding conventions, tests, and what to include in a pull request. For a substantial feature or architectural change, open an issue to discuss the intended behavior first. Share only PDF samples you have permission to publish and remove private information.
Start with the English overview above. Some detailed architecture and pipeline documents are currently in Vietnamese; documentation translations are welcome.
- Architecture: source map, C++ guide, QML guide, and page overlays.
- Editing: text and save pipeline, fonts, tables, comments, and headers/footers.
- Document operations: merge, split, and watermarks.
- Conversion: OCR and Excel export.
- Development: tests, QML profiling, and repository implementation guidance.
TrePDF's source is licensed under the Apache License 2.0.
Third-party libraries, fonts, icons, and test fixtures retain their own licenses.
See the notices in third_party/ and the relevant asset directories, including
qpdf, OCR,
libxlsxwriter, and
icons.