- Copyright (c) 2015 Stefan Lehmann
- License: MIT
- Description: Python-based command line tool for manipulating PDFs. It is based on the pypdf package.
Ideally, you should be able to clone this repo and run pip install -e . to install the package locally.
On OSX, I had to go into ~/Library/Python/<python-version>/lib/python/site-packages/easy-install.pth and add the local repo directory.
- add, insert, remove and rotate pages
- split PDF files in multiple documents
- copy specific pages in a new document
- merge or zip PDF files into one document
- set page labels (roman/decimal/letter numbering, custom prefixes)
pdftools adds some scripts to your existing Python installation that can be called via the command line. The description for each script is listed below.
Breaking change: The copy and insert commands have been consolidated into add:
-
pdftools copy src.pdf out.pdf -p 1-3→pdftools add src.pdf out.pdf -p 1-3 -
pdftools insert dest.pdf src.pdf -p 1-3 -i 2→pdftools add src.pdf dest.pdf -p 1-3 -i 2 -
pdftools add dest.pdf src.pdf -p 1-3→pdftools add src.pdf dest.pdf -p 1-3(note: argument order reversed)
Separating list options from positional arguments. Options that take a
list of values, such as -p/--pages or -q/--sequence, greedily consume
every argument that follows them. If you place one of these options before a
positional argument like dest or src, the option swallows the file name and
the command fails with a "following arguments are required" error. Use -- to
mark the end of the option's values, for example:
pdftools add -p 1-3 -- src.pdf dest.pdf
Placing the positional arguments first avoids the problem entirely:
pdftools add src.pdf dest.pdf -p 1-3
usage: pdftools [-h] [-V] <command> ...
Python-based command line tool for manipulating PDFs. It is based on the
pypdf package.
optional arguments:
-h, --help show this help message and exit
-V, --version Print version number and exit (default: False)
Sub-commands:
<command>
add Add pages from a source file to a destination PDF file
merge Merge the pages of multiple input files into one output file
remove Remove pages from a PDF file
rotate Rotate the pages of a PDF files by 90 degrees
crop Crop the pages of a PDF file by pixels wrt mediabox
label Set page labels (numbering style) for a PDF file
split Split a PDF file into multiple documents
zip Python-like zipping (interleaving) the pages of two documents
in one output file
Add pages from a source PDF to a destination PDF. If the destination doesn't exist, it will be created. Pages can be inserted at any position, or appended to the end.
usage: pdftools add [-h] [-p PAGES [PAGES ...]] [-i INDEX] [-o OUTPUT] [-f]
src dest
Positional arguments:
src Source PDF file
dest Destination PDF file (created if it doesn't exist)
Options:
-h, --help show this help message and exit
-p PAGES [PAGES ...], --pages PAGES [PAGES ...]
Pages from source to add. Examples: 5; 1-9; 1-; -9
(default: all pages)
-i INDEX, --index INDEX
1-indexed position in dest where pages will be inserted.
If omitted, pages are appended to the end. (default: None)
-o OUTPUT, --output OUTPUT
Output file. If omitted, dest is overwritten in-place.
(default: None)
-f, --force Skip all overwrite confirmation prompts (default: False)
note: options that take a list of values (e.g. -p/--pages) will consume any
file names that follow them. If you place such an option before a positional
argument like `src` or `dest`, separate them with `--`, for example:
pdftools add -p 1-3 -- src.pdf dest.pdf
Examples:
# Create a new file with pages 1-3 from source
pdftools add src.pdf out.pdf -p 1-3
# Append all pages from src to dest (overwrite dest)
pdftools add src.pdf dest.pdf
# Insert pages 2-5 from src at position 3 in dest
pdftools add src.pdf dest.pdf -p 2-5 -i 3
# Write to a different output file
pdftools add src.pdf dest.pdf -p 1-3 -o combined.pdf
# Force overwrite without prompting
pdftools add src.pdf dest.pdf -fusage: pdftools remove [-h] [-f] [-o OUTPUT] src pages [pages ...]
Remove pages from a PDF file
positional arguments:
src PDF source file
pages List of pages to remove from file. Examples: 5; 1-9;
1-; -9
options:
-h, --help show this help message and exit
-f, --force Caution!! Answers "Yes" to all overwrite queries.
(default: False)
-o OUTPUT, --output OUTPUT
Name of the output file. If None, the `src` file will
be overwritten (default: None)
usage: pdftools rotate [-h] [-d {90,180,270}] [-c] [-p PAGES [PAGES ...]]
[-o OUTPUT]
src
Rotate the pages of a PDF file by a set number of degrees
positional arguments:
src Source file
optional arguments:
-h, --help show this help message and exit
-d {90,180,270}, --degrees {90,180,270}
Specify degrees value to rotate page(s) (default: 90)
-c, --counter-clockwise
Rotate pages counter-clockwise instead of clockwise,
by default (default: False)
-p PAGES [PAGES ...], --pages PAGES [PAGES ...]
List of page numbers which will be rotated. If None,
all pages will be rotated. Examples: 5; 1-9; 1-; -9
(default: None)
-o OUTPUT, --output OUTPUT
Output filename. If None, the source file will be
overwritten (default: None)
note: options that take a list of values (e.g. -p/--pages) will consume any
file names that follow them. If you place such an option before a positional
argument like `src` or `dest`, separate them with `--`, for example: pdftools
add -p 1-3 -- dest.pdf src.pdf
usage: pdftools crop [-h] [-l pix] [-b pix] [-r pix] [-t pix] [-p PAGES [PAGES ...]]
[-o OUTPUT]
src
Crop the pages of a PDF file by pixels from edges (left, bottom, right, top)
positional arguments:
src Source file
optional arguments:
-h, --help show this help message and exit
-l, --left For each side, crop the given number of pixels INSIDE
-r, --right the mediabox. This tool only affects the cropbox, so
-b, --bottom using the default values (all 0) sets the PDF back to
-t, --top its original dimensions.
-p PAGES [PAGES ...], --pages PAGES [PAGES ...]
List of page numbers which will be rotated. If None,
all pages will be rotated. Examples: 5; 1-9; 1-; -9
(default: None)
-o OUTPUT, --output OUTPUT
Output filename. If None, the source file will be
overwritten (default: None)
note: options that take a list of values (e.g. -p/--pages) will consume any
file names that follow them. If you place such an option before a positional
argument like `src` or `dest`, separate them with `--`, for example: pdftools
add -p 1-3 -- dest.pdf src.pdf
Set page labels (the human-facing page identifiers shown in PDF viewers) for a range of pages.
The label range starts at --start-page and continues to the end of the document.
Run the command multiple times to create different sections (e.g., roman numerals for front matter,
decimal for body); earlier label ranges are preserved.
usage: pdftools label [-h] [-s START_PAGE]
[--style {decimal,roman,roman-lower,ROMAN,roman-upper,
letters,letters-lower,LETTERS,letters-upper}]
[--prefix PREFIX] [-n NUMBER] [-o OUTPUT] [-f]
src
positional arguments:
src Source PDF file
optional arguments:
-h, --help show this help message and exit
-s, --start-page START_PAGE
First page of the labeled section (1-indexed)
(default: 1)
--style {decimal,roman,roman-lower,ROMAN,roman-upper,letters,letters-lower,LETTERS,letters-upper}
Numbering style for page labels (default: None)
--prefix PREFIX String prefix for labels (e.g., 'A-' or 'Chapter ')
(default: None)
-n, --number NUMBER Numeric value of the first label in the range
(default: 1)
-o OUTPUT, --output OUTPUT
Output filename. If None, the source file will be
overwritten (default: None)
-f, --force Caution!! Answers "Yes" to all overwrite queries.
(default: False)
Examples:
Create a document with roman numeral front matter (pages 1-2) and decimal body (pages 3 onward):
# First, label pages 1-2 as roman numerals (i, ii)
pdftools label document.pdf --style roman -f
# Then, label from page 3 onward as decimal starting at 1
pdftools label document.pdf -s 3 --style decimal -fThe result will show page labels: i, ii, 1, 2, 3, ...
Add a prefix to labels:
pdftools label document.pdf -s 5 --style decimal --prefix "A-" -fThis labels pages 5 onward as: A-1, A-2, A-3, ...
usage: pdftools split [-h] [-s STEPSIZE] [-q SEQUENCE [SEQUENCE ...]]
[-o OUTPUT]
src
Split a PDF file into multiple documents
positional arguments:
src Source file to be split
options:
-h, --help show this help message and exit
-s STEPSIZE, --stepsize STEPSIZE
How many pages are packed in each output file
(default: 1)
-q SEQUENCE [SEQUENCE ...], --sequence SEQUENCE [SEQUENCE ...]
Sequence of numbers describing how many pages to put
in each outputfile (default: None)
-o OUTPUT, --output OUTPUT
Output filenames. If None, will append page numbers to
the input file name. (default: None)
note: options that take a list of values (e.g. -p/--pages) will consume any
file names that follow them. If you place such an option before a positional
argument like `src` or `dest`, separate them with `--`, for example: pdftools
add -p 1-3 -- dest.pdf src.pdf
usage: pdftools merge [-h] [-d] [-o OUTPUT] src [src ...]
Merge the pages of multiple input files into one output file
positional arguments:
src List of input source files
options:
-h, --help show this help message and exit
-d, --delete Delete source files after merge (default: False)
-o OUTPUT, --output OUTPUT
Output filename (default: merged.pdf)
usage: pdftools zip [-h] [-d] [-r] src1 src2 output
Python-like zipping (interleaving) the pages of two documents in one output
file
positional arguments:
src1 First source file
src2 Second source file
output Name of the output file
optional arguments:
-h, --help show this help message and exit
-d, --delete Delete source files after merge (default: False)
-r, --reverse Reverse the pages of second input file (default: False)