rgPDF
繁體中文 · English
The official application name is rgPDF; the command and Python package remain rgpdf.
rgPDF is a cross-platform desktop application for searching text-layer PDFs and Word documents with plain text or regular expressions. Matches appear as they are found and can be opened in an asynchronous page preview with precise, configurable highlighting.
Features
- Search PDFs, Word documents (
.docand.docx), or both in a folder, optionally including subfolders. - Plain-text and regular-expression modes with optional case sensitivity.
- Matches across lines and page boundaries, including line-end dehyphenation.
- Incremental per-match results without blocking the interface.
- Three coordinated views for files, matching passages, and PDF page preview.
- Per-character highlight geometry and configurable highlight colors.
- English and Traditional Chinese interfaces, plus system/light/dark themes.
- Persistent search and appearance preferences.
rgPDF searches existing PDF text layers. Word documents are converted to a cached PDF and then use the same search and preview pipeline. On Windows, Microsoft Word is tried first; LibreOffice is the cross-platform fallback. At least one of them must already be installed to search Word files. Cached conversions unused for 30 days are removed at startup; the cache is reduced by least-recent use when it exceeds 500 MB, and it can be cleared from the toolbar. rgPDF never runs document macros, does not perform OCR, and does not modify source files.
Usage
The Filename stem filter below Document folder optionally limits which files are searched. Click the help icon immediately to the left of its input field to open syntax explanations and examples, just like Search pattern help. Leave it empty for no filter. It matches the entire filename without its last extension, ignoring case, and supports * (any string), ? (one character), [abc], [0-9], and [!abc]. For example, ch0* includes ch01.pdf and ch02.docx but excludes ch1.pdf and ch2.docx; ch01 matches that exact stem. The filter applies before PDF reading or Word conversion and works together with file-type and subfolder settings. It is saved between sessions and is independent of the text search’s regex and case settings.
Choose a folder with Browse, enter text or a regular expression, and click Search. Select a file and matching passage to preview its page and highlight. Use the preview’s Previous page / Next page buttons to browse all document pages, including pages without a match. Select another passage in the match pane to jump to its matched page. Fit page scales the whole page to the preview’s width and height and adapts when the pane is resized; Fit width remains available for reading at a larger size. The toolbar controls below are listed in their on-screen order. Hover over a button to see its current setting; clicking a three-state button cycles modes.
| Toolbar icon | Control | Usage |
|---|---|---|
| Include subfolders | Toggle recursive folder search. | |
| File types | Cycle PDF → Word (DOC/DOCX) → both. Word requires Microsoft Word on Windows or LibreOffice. | |
| Case sensitive | Toggle case-sensitive matching. | |
| Regular expression | Toggle regex; use the help icon beside the search field for examples. | |
| Highlight color | Choose a preset or custom color. | |
| Clear Word cache | Confirm deletion of conversion PDFs; original Word files are preserved. Disabled during search. | |
| Language | Cycle system → Traditional Chinese → English. | |
| Color theme | Cycle system → light → dark. | |
| About | View version, license, and source links. |
All action buttons use icons; hover to see their original labels in the selected language. Search, color, and preview controls:
| Icon | Tooltip / action |
|---|---|
| Browse… | |
| Search | |
| Cancel | |
| Search pattern help | |
| Custom color… | |
| Previous page | |
| Next page | |
| Zoom out | |
| Zoom in | |
| Fit width | |
| Fit page |
Search settings are saved between sessions. Conversion cache is cleaned at startup: entries unused for 30 days expire, then the oldest entries are removed if total size exceeds 500 MB. Use Cancel to stop a search.
Install the latest release
Windows standalone download
Download the versioned rgpdf-*-windows-x86_64.exe and its .sha256 file
from the latest GitHub Release.
The executable is currently unsigned, so Windows SmartScreen may show an
unknown-publisher warning. Verify that the SHA-256 value matches the published
file before choosing to run it.
No Python or uv installation is required for the standalone executable. PDF search has no additional requirement. Word search requires an existing Microsoft Word installation on Windows or an existing LibreOffice installation.
macOS App (Apple Silicon)
Download the versioned rgpdf-*-macos-arm64.dmg and its .sha256 file from
the latest GitHub Release.
Verify the download first:
shasum -a 256 rgpdf-*-macos-arm64.dmg
After confirming that the output matches the .sha256 file, open the DMG and
drag rgpdf.app to Applications. This build supports Apple Silicon (M-series)
Macs and does not require Python or uv.
The App is ad-hoc signed and not notarized by Apple. If macOS blocks its first
launch, Control-click rgpdf in Finder's Applications folder, choose Open,
then choose Open again in the confirmation dialog.
Install with uv
Install uv, then install the latest release from PyPI:
uv tool install rgpdf
Run the application:
rgpdf
To update an existing installation:
uv tool upgrade rgpdf
Windows and macOS are supported; uv manages the required Python environment.
To install the latest source release directly from GitHub instead, use the moving latest tag:
uv tool install "git+https://github.com/codemee/rgpdf.git@latest"
Development
git clone https://github.com/codemee/rgpdf.git
cd rgpdf
uv sync
uv run pytest
uv run rgpdf
Local development runs tests and the application with uv. Executable and App artifacts are built remotely by GitHub Actions when a version tag is pushed; do not build them locally. The release includes a Windows single executable, a macOS Apple Silicon DMG, checksums, and corresponding source archives.
After toolbar artwork changes, regenerate the README images with
uv run python scripts/generate_toolbar_icons.py.
See Technical details for architecture, matching semantics, concurrency, and release engineering. Version history is in the changelog.
Releases
Immutable releases use version tags such as v0.0.3. The movable latest Git tag always points to the newest published source release. PyPI provides the canonical packaged release.
Releases are automated with GitHub Actions. After making the versions in
pyproject.toml and src/rgpdf/__init__.py match, push the corresponding tag:
git tag v0.0.8
git push origin v0.0.8
The workflow tests and builds Windows x86_64 and macOS arm64 in parallel, downloads and verifies the locked third-party corresponding sources, creates one GitHub Release with checksums, then publishes to PyPI through Trusted Publishing. A failed test, build, or source verification prevents publication.
License
rgPDF is licensed under the GNU Affero General Public License version 3. You may use, study, modify, and redistribute it under the terms of that license. Distributed binaries must be accompanied by the complete corresponding source for the same version.
This application uses PyMuPDF/MuPDF under AGPLv3 and PySide6/Qt under LGPLv3. See third-party notices and the release compliance checklist.
Metadata
Release files for rgpdf 0.0.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rgpdf-0.0.9.tar.gz | 109.1 kB | With provenance | Details for rgpdf-0.0.9.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rgpdf-0.0.9-py3-none-any.whl | Python 3 | none | any | Details for rgpdf-0.0.9-py3-none-any.whl |
Total release size: 157.0 kB
Release files / rgpdf-0.0.9.tar.gz
| Download URL | rgpdf-0.0.9.tar.gz |
|---|---|
| Size | 109.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fac6c4b9fef3175756203fb886435ac92858aeb432af75bb9ca7cd3cb155023c
|
|
BLAKE2b-256 checksum How to use checksums |
d75342bddd91e149efe5a12dc9e0a5048ed3885b9ae6561debdad77c608982ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logRelease files / rgpdf-0.0.9-py3-none-any.whl
| Download URL | rgpdf-0.0.9-py3-none-any.whl |
|---|---|
| Size | 47.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c1bad5b496c4c06585c20f40c62f7a29fef77cb19b0b11e50d0d2a46ad2e4f12
|
|
BLAKE2b-256 checksum How to use checksums |
741633d3c086ab97d90d88a316ec97a564a4d5e1b3be8ec6586c57983ebc9e22
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logSecurity for rgpdf 0.0.9
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for rgpdf-0.0.9.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.