PyCropPDF
PyCropPDF is a desktop PDF editor for cropping, rotating, and visually covering PDF pages.

Install
Standalone builds
The latest release provides
x86_64 builds for Windows (.exe) and Linux (.AppImage). Both include Auto deskew.
On Linux:
chmod +x PyCropPDF-*-x86_64.AppImage
./PyCropPDF-*-x86_64.AppImage
AppImage normally uses FUSE 2. If FUSE is unavailable, run it without mounting:
APPIMAGE_EXTRACT_AND_RUN=1 ./PyCropPDF-*-x86_64.AppImage
PyPI
PyCropPDF requires Python 3.11 or later.
python -m pip install pycroppdf
Auto deskew is optional because it adds NumPy and scikit-image:
python -m pip install "pycroppdf[deskew]"
Run
pycroppdf
pycroppdf --input /path/to/document.pdf
Optional arguments:
--save-to DIRECTORY saves to that directory instead of opening a Save dialog.
--save-as NAME.pdf sets the output name when used with --save-to. Without it, --save-to writes <input>_modified.pdf.
--manifest-out PATH sets the JSON provenance-manifest path. By default it is saved next to the PDF as <output>.pycroppdf.json.
Edit a PDF
- Open a PDF with File > Open PDF... or drag it into the window.
- Use View to choose one overlay for all pages or separate odd/even overlays.
- Click a thumbnail image to preview that page. Click it again or use Stack to return. Thumbnail checkboxes select pages for deletion;
Ctrl/Cmd toggles and Shift selects a range.
- Open Rotate, choose all, odd, even, or the previewed page, and enter an angle. Click Preview to inspect a fine rotation, Discard to clear it, or Apply to change the PDF. The 90-degree buttons apply immediately; Auto deskew detects and corrects small angles per page.
- Click Cover, choose All, Odd, or Even, then draw the cover. In a page preview, This page only overrides that scope. Cover works inside an active crop and before or after applied rotation. New covers are added without replacing existing ones and do not remove the underlying PDF content.
- Click Crop, draw a crop box, then click Apply Crop. Odd/even positions are independent and their sizes stay uniform. To override one page, preview it, enable This page only, draw its crop box, and apply the crop again.
- Use Undo or
Ctrl+Z to revert one edit. Use Reload to discard all edits and reopen the original PDF from disk. Click Save to export the result.
Crop applies to all pages. Cover uses its selected scope and remains additive. A per-page crop override replaces the stack crop only for that page.
Rendering and Auto deskew show progress and a Cancel button; Escape also cancels.
Work already in progress, including a page render or PDF write, finishes before
cancellation completes. Cancelling Auto deskew leaves the document unchanged and
preserves Undo history. Cancelling previews preserves committed edits;
choose Retry previews before drawing another crop or cover. You can still save
the document or undo committed edits. Closing during rendering or Auto deskew requests
cancellation, then uses the normal unsaved-changes confirmation after cleanup.
Stack overlays preserve the darkest ink from every page. White backgrounds do not
hide marks from earlier pages, so isolated headers and footers remain visible in
large stacks. Inspect individual pages when overlapping content becomes dense.
Ready thumbnails can be opened while the remaining pages render. In the sidebar,
use arrow keys to move, Enter to preview, and Space to check a page for deletion.
Retries reuse completed previews; editing a page refreshes its preview without
rendering unaffected pages again.
Page images, thumbnails, and reusable overlay groups share a 500 MiB cache budget
allocated as needed. Least recently used page buffers spill to private compressed
temporary files when the budget fills. Partial edits reuse unchanged overlay groups
for ordinary page sizes, as well as unchanged page buffers. Group storage uses at
most a quarter of the cache budget and stays in RAM. PDF documents, current display
overlays, display buffers, and worker processes use additional memory.
Very large pages use previews capped at 2,048 pixels on the longest side. Crop
coordinates and exported PDF content retain their original precision; zoomed
previews of unusually large pages may show less detail.
Rotation, Auto deskew, and Cover remain available after cropping. Affected crop boxes follow the rotated pages; fine rotation expands their bounding boxes so cropped content is not cut at the corners. Apply or discard a rotation preview before drawing a cover. For pages with links, annotations, or form fields, the app warns before a fine-angle rotation because some appearances or destinations cannot be transformed exactly.
Tools
| Tool |
Effect |
| Crop Box |
Changes the PDF CropBox. The content outside the visible area remains in the file. |
| Cover |
Adds a rectangle to all, odd, even, or only the previewed page. Existing covers and covered content remain in the file. |
| Rotation |
Rotates page content without rasterizing it. Exact 90-degree turns use PDF rotation metadata. |
| Auto deskew |
Detects a small text-line angle independently for each target page. Requires pycroppdf[deskew]. |
Crop boxes and covers change presentation; they do not securely remove content.
Larger Auto deskew jobs use one fewer worker than the detected CPU count. Two-core systems use both cores. Small jobs stay in one process to avoid startup overhead.
Provenance manifest
Each save writes a JSON sidecar manifest unless a different path is supplied with --manifest-out. It records source and output SHA-256 hashes, page mapping and deletions, rotations, and crop and cover rectangles.
Development
git clone https://github.com/lukaszliniewicz/PyCropPDF.git
cd PyCropPDF
python -m pip install -e ".[dev,deskew]"
pytest
ruff check .
ruff format --check .
For reproducible development dependencies and the full static-check policy (Ruff,
Basedpyright, Vulture, and import-cycle/layer checks), see CONTRIBUTING.md.
The staged improvement work and its acceptance checks are in IMPLEMENTATION_PLAN.md.
Build versioned standalone release files from the locked environment:
uv sync --locked --extra build --extra deskew
uv run --no-sync python scripts/build_release.py
Windows builds produce an .exe; Linux builds additionally require the verified
AppImage tools. See the release-build instructions
for tool pins, runtime checks, and publication steps. The manually dispatched
Release builds workflow builds and checks both platforms. Auto deskew is included.
The existing scripts/build_windows.ps1 remains available for custom Windows builds.
License
MIT
Standalone builds also include third-party components with their own license terms.
Release downloads provide dependency notices and build records alongside the binaries;
the project's MIT license does not replace those third-party terms.