Module fitz

  • New in version 1.16.8

PyMuPDF can also be used in the command line as a module to perform utility functions. This feature should obsolete writing some of the most basic scripts.

Admittedly, there is some functional overlap with the MuPDF CLI mutool. On the other hand, PDF embedded files are no longer supported by MuPDF, so PyMuPDF is offering something unique here.

Invocation

Invoke the module like this:

  1. python -m fitz <command and parameters>

General remarks:

  • Request help via "-h", resp. command-specific help via "command -h".

  • Parameters may be abbreviated where this does not introduce ambiguities.

  • Several commands support parameters -pages and -xrefs. They are intended for down-selection. Please note that:

    • page numbers for this utility must be given 1-based.

    • valid xref numbers start at 1.

    • Specify a comma-separated list of either single integers or integer ranges. A range is a pair of integers separated by one hyphen “-“. Integers must not exceed the maximum page, resp. xref number. To specify that maximum, the symbolic variable “N” may be used. Integers or ranges may occur several times, in any sequence and may overlap. If in a range the first number is greater than the second one, the respective items will be processed in reversed order.

  • How to use the module inside your script:

    1. >>> from fitz.__main__ import main as fitz_command
    2. >>> cmd = "clean input.pdf output.pdf -pages 1,N".split()  # prepare command line
    3. >>> saved_parms = sys.argv[1:]  # save original command line
    4. >>> sys.argv[1:] = cmd  # store new command line
    5. >>> fitz_command()  # execute module
    6. >>> sys.argv[1:] = saved_parms  # restore original command line

  • Use the following 2-liner and compile it with Nuitka in standalone mode. This will give you a CLI executable with all the module’s features, that can be used on all compatible platforms without Python, PyMuPDF or MuPDF being installed.

  1. from fitz.__main__ import main
  2. main()

Cleaning and Copying

This command will optimize the PDF and store the result in a new file. You can use it also for encryption, decryption and creating sub documents. It is mostly similar to the MuPDF command line utility “mutool clean”:

  1. python -m fitz clean -h
  2. usage: fitz clean [-h] [-password PASSWORD]
  3.                 [-encryption {keep,none,rc4-40,rc4-128,aes-128,aes-256}]
  4.                 [-owner OWNER] [-user USER] [-garbage {0,1,2,3,4}]
  5.                 [-compress] [-ascii] [-linear] [-permission PERMISSION]
  6.                 [-sanitize] [-pretty] [-pages PAGES]
  7.                 input output
  9. -------------- optimize PDF or create sub-PDF if pages given --------------
  11. positional arguments:
  12. input                 PDF filename
  13. output                output PDF filename
  15. optional arguments:
  16. -h, --help            show this help message and exit
  17. -password PASSWORD    password
  18. -encryption {keep,none,rc4-40,rc4-128,aes-128,aes-256}
  19.                       encryption method
  20. -owner OWNER          owner password
  21. -user USER            user password
  22. -garbage {0,1,2,3,4}  garbage collection level
  23. -compress             compress (deflate) output
  24. -ascii                ASCII encode binary data
  25. -linear               format for fast web display
  26. -permission PERMISSION
  27.                       integer with permission levels
  28. -sanitize             sanitize / clean contents
  29. -pretty               prettify PDF structure
  30. -pages PAGES          output selected pages, format: 1,5-7,50-N

If you specify “-pages”, be aware that only page-related objects are copied, no document-level items like e.g. embedded files.

Please consult Document.save() for the parameter meanings.

Extracting Fonts and Images

Extract fonts or images from selected PDF pages to a desired directory:

  1. python -m fitz extract -h
  2. usage: fitz extract [-h] [-images] [-fonts] [-output OUTPUT] [-password PASSWORD]
  3.                     [-pages PAGES]
  4.                     input
  6. --------------------- extract images and fonts to disk --------------------
  8. positional arguments:
  9. input                 PDF filename
  11. optional arguments:
  12. -h, --help            show this help message and exit
  13. -images               extract images
  14. -fonts                extract fonts
  15. -output OUTPUT        output directory, defaults to current
  16. -password PASSWORD    password
  17. -pages PAGES          only consider these pages, format: 1,5-7,50-N

Image filenames are built according to the naming scheme: “img-xref.ext”, where “ext” is the extension associated with the image and “xref” the xref of the image PDF object.

Font filenames consist of the fontname and the associated extension. Any spaces in the fontname are replaced with hyphens “-“.

The output directory must already exist.

Note

Except for output directory creation, this feature is functionally equivalent to and obsoletes this script.

Joining PDF Documents

To join several PDF files specify:

  1. python -m fitz join -h
  2. usage: fitz join [-h] -output OUTPUT [input [input ...]]
  4. ---------------------------- join PDF documents ---------------------------
  6. positional arguments:
  7. input           input filenames
  9. optional arguments:
  10. -h, --help      show this help message and exit
  11. -output OUTPUT  output filename
  13. specify each input as 'filename[,password[,pages]]'

Note

  1. Each input must be entered as “filename,password,pages”. Password and pages are optional.

  2. The password entry is required if the “pages” entry is used. If the PDF needs no password, specify two commas.

  3. The “pages” format is the same as explained at the top of this section.

  4. Each input file is immediately closed after use. Therefore you can use one of them as output filename, and thus overwrite it.

Example: To join the following files

  1. file1.pdf: all pages, back to front, no password

  2. file2.pdf: last page, first page, password: “secret”

  3. file3.pdf: pages 5 to last, no password

and store the result as output.pdf enter this command:

python -m fitz join -o output.pdf file1.pdf,,N-1 file2.pdf,secret,N,1 file3.pdf,,5-N

Low Level Information

Display PDF internal information. Again, there are similarities to “mutool show”:

  1. python -m fitz show -h
  2. usage: fitz show [-h] [-password PASSWORD] [-catalog] [-trailer] [-metadata]
  3.                 [-xrefs XREFS] [-pages PAGES]
  4.                 input
  6. ------------------------- display PDF information -------------------------
  8. positional arguments:
  9. input               PDF filename
  11. optional arguments:
  12. -h, --help          show this help message and exit
  13. -password PASSWORD  password
  14. -catalog            show PDF catalog
  15. -trailer            show PDF trailer
  16. -metadata           show PDF metadata
  17. -xrefs XREFS        show selected objects, format: 1,5-7,N
  18. -pages PAGES        show selected pages, format: 1,5-7,50-N

Examples:

  1. python -m fitz show x.pdf
  2. PDF is password protected
  4. python -m fitz show x.pdf -pass hugo
  5. authentication unsuccessful
  7. python -m fitz show x.pdf -pass jorjmckie
  8. authenticated as owner
  9. file 'x.pdf', pages: 1, objects: 19, 58 MB, PDF 1.4, encryption: Standard V5 R6 256-bit AES
  10. Document contains 15 embedded files.
  12. python -m fitz show FDA-1572_508_R6_FINAL.pdf -tr -m
  13. 'FDA-1572_508_R6_FINAL.pdf', pages: 2, objects: 1645, 1.4 MB, PDF 1.6, encryption: Standard V4 R4 128-bit AES
  14. document contains 740 root form fields and is signed
  16. ------------------------------- PDF metadata ------------------------------
  17.        format: PDF 1.6
  18.         title: FORM FDA 1572
  19.        author: PSC Publishing Services
  20.       subject: Statement of Investigator
  21.      keywords: None
  22.       creator: PScript5.dll Version 5.2.2
  23.      producer: Acrobat Distiller 9.0.0 (Windows)
  24.  creationDate: D:20130522104413-04'00'
  25.       modDate: D:20190718154905-07'00'
  26.    encryption: Standard V4 R4 128-bit AES
  28. ------------------------------- PDF trailer -------------------------------
  29. <<
  30. /DecodeParms <<
  31.     /Columns 5
  32.     /Predictor 12
  33. >>
  34. /Encrypt 1389 0 R
  35. /Filter /FlateDecode
  36. /ID [ <9252E9E39183F2A0B0C51BE557B8A8FC> <85227BE9B84B724E8F678E1529BA8351> ]
  37. /Index [ 1388 258 ]
  38. /Info 1387 0 R
  39. /Length 253
  40. /Prev 1510559
  41. /Root 1390 0 R
  42. /Size 1646
  43. /Type /XRef
  44. /W [ 1 3 1 ]
  45. >>

Embedded Files Commands

The following commands deal with embedded files – which is a feature completely removed from MuPDF after v1.14, and hence from all its command line tools.

Information

Show the embedded file names (long or short format):

  1. python -m fitz embed-info -h
  2. usage: fitz embed-info [-h] [-name NAME] [-detail] [-password PASSWORD] input
  4. --------------------------- list embedded files ---------------------------
  6. positional arguments:
  7. input               PDF filename
  9. optional arguments:
  10. -h, --help          show this help message and exit
  11. -name NAME          if given, report only this one
  12. -detail             show detail information
  13. -password PASSWORD  password

Example:

  1. python -m fitz embed-info some.pdf
  2. 'some.pdf' contains the following 15 embedded files.
  4. 20110813_180956_0002.jpg
  5. 20110813_181009_0003.jpg
  6. 20110813_181012_0004.jpg
  7. 20110813_181131_0005.jpg
  8. 20110813_181144_0006.jpg
  9. 20110813_181306_0007.jpg
  10. 20110813_181307_0008.jpg
  11. 20110813_181314_0009.jpg
  12. 20110813_181315_0010.jpg
  13. 20110813_181324_0011.jpg
  14. 20110813_181339_0012.jpg
  15. 20110813_181913_0013.jpg
  16. insta-20110813_180944_0001.jpg
  17. markiert-20110813_180944_0001.jpg
  18. neue.datei

Detailed output would look like this per entry:

  1.      name: neue.datei
  2.  filename: text-tester.pdf
  3. ufilename: text-tester.pdf
  4.      desc: nur zum Testen!
  5.      size: 4639
  6.    length: 1566

Extraction

Extract an embedded file like this:

  1. python -m fitz embed-extract -h
  2. usage: fitz embed-extract [-h] -name NAME [-password PASSWORD] [-output OUTPUT]
  3.                         input
  5. ---------------------- extract embedded file to disk ----------------------
  7. positional arguments:
  8. input                 PDF filename
  10. optional arguments:
  11. -h, --help            show this help message and exit
  12. -name NAME            name of entry
  13. -password PASSWORD    password
  14. -output OUTPUT        output filename, default is stored name

For details consult Document.embfile_get(). Example (refer to previous section):

  1. python -m fitz embed-extract some.pdf -name neue.datei
  2. Saved entry 'neue.datei' as 'text-tester.pdf'

Deletion

Delete an embedded file like this:

  1. python -m fitz embed-del -h
  2. usage: fitz embed-del [-h] [-password PASSWORD] [-output OUTPUT] -name NAME input
  4. --------------------------- delete embedded file --------------------------
  6. positional arguments:
  7. input                 PDF filename
  9. optional arguments:
  10. -h, --help            show this help message and exit
  11. -password PASSWORD    password
  12. -output OUTPUT        output PDF filename, incremental save if none
  13. -name NAME            name of entry to delete

For details consult Document.embfile_del().

Insertion

Add a new embedded file using this command:

  1. python -m fitz embed-add -h
  2. usage: fitz embed-add [-h] [-password PASSWORD] [-output OUTPUT] -name NAME -path
  3.                     PATH [-desc DESC]
  4.                     input
  6. ---------------------------- add embedded file ----------------------------
  8. positional arguments:
  9. input                 PDF filename
  11. optional arguments:
  12. -h, --help            show this help message and exit
  13. -password PASSWORD    password
  14. -output OUTPUT        output PDF filename, incremental save if none
  15. -name NAME            name of new entry
  16. -path PATH            path to data for new entry
  17. -desc DESC            description of new entry

“NAME” must not already exist in the PDF. For details consult Document.embfile_add().

Updates

Update an existing embedded file using this command:

  1. python -m fitz embed-upd -h
  2. usage: fitz embed-upd [-h] -name NAME [-password PASSWORD] [-output OUTPUT]
  3.                     [-path PATH] [-filename FILENAME] [-ufilename UFILENAME]
  4.                     [-desc DESC]
  5.                     input
  7. --------------------------- update embedded file --------------------------
  9. positional arguments:
  10. input                 PDF filename
  12. optional arguments:
  13. -h, --help            show this help message and exit
  14. -name NAME            name of entry
  15. -password PASSWORD    password
  16. -output OUTPUT        Output PDF filename, incremental save if none
  17. -path PATH            path to new data for entry
  18. -filename FILENAME    new filename to store in entry
  19. -ufilename UFILENAME  new unicode filename to store in entry
  20. -desc DESC            new description to store in entry
  22. except '-name' all parameters are optional

Use this method to change meta-information of the file – just omit the “PATH”. For details consult Document.embfile_upd().

Copying

Copy embedded files between PDFs:

  1. python -m fitz embed-copy -h
  2. usage: fitz embed-copy [-h] [-password PASSWORD] [-output OUTPUT] -source
  3.                     SOURCE [-pwdsource PWDSOURCE]
  4.                     [-name [NAME [NAME ...]]]
  5.                     input
  7. --------------------- copy embedded files between PDFs --------------------
  9. positional arguments:
  10. input                 PDF to receive embedded files
  12. optional arguments:
  13. -h, --help            show this help message and exit
  14. -password PASSWORD    password of input
  15. -output OUTPUT        output PDF, incremental save to 'input' if omitted
  16. -source SOURCE        copy embedded files from here
  17. -pwdsource PWDSOURCE  password of 'source' PDF
  18. -name [NAME [NAME ...]]
  19.                       restrict copy to these entries

Text Extraction

  • New in v1.18.16

Extract text from arbitrary supported documents (not only PDF) to a textfile. Currently, there are three output formatting modes available: simple, block sorting and reproduction of physical layout.

  • Simple text extraction reproduces all text as it appears in the document pages – no effort is made to rearrange in any particular reading order.

  • Block sorting sorts text blocks (as identified by MuPDF) by ascending vertical, then horizontal coordinates. This should be sufficient to establish a “natural” reading order for basic pages of text.

  • Layout strives to reproduce the original appearance of the input pages. You can expect results like this (produced by the command python -m fitz gettext -pages 1 demo1.pdf):

_images/img-layout-text.jpg

Note

The “gettext” command offers a functionality similar to the CLI tool pdftotext by XPDF software, http://www.foolabs.com/xpdf/ – this is especially true for “layout” mode, which combines that tool’s -layout and -table options.

After each page of the output file, a formfeed character, hex(12) is written – even if the input page has no text at all. This behavior can be controlled via options.

Note

For “layout” mode, only horizontal, left-to-right, top-to bottom text is supported, other text is ignored. In this mode, text is also ignored, if its fontsize is too small.

“Simple” and “blocks” mode in contrast output all text for any text size or orientation.

Command:

  1. python -m fitz gettext -h
  2. usage: fitz gettext [-h] [-password PASSWORD] [-mode {simple,blocks,layout}] [-pages PAGES] [-noligatures]
  3.                     [-convert-white] [-extra-spaces] [-noformfeed] [-skip-empty] [-output OUTPUT] [-grid GRID]
  4.                     [-fontsize FONTSIZE]
  5.                     input
  7. ----------------- extract text in various formatting modes ----------------
  9. positional arguments:
  10. input                 input document filename
  12. optional arguments:
  13. -h, --help            show this help message and exit
  14. -password PASSWORD    password for input document
  15. -mode {simple,blocks,layout}
  16.                         mode: simple, block sort, or layout (default)
  17. -pages PAGES          select pages, format: 1,5-7,50-N
  18. -noligatures          expand ligature characters (default False)
  19. -convert-white        convert whitespace characters to space (default False)
  20. -extra-spaces         fill gaps with spaces (default False)
  21. -noformfeed           write linefeeds, no formfeeds (default False)
  22. -skip-empty           suppress pages with no text (default False)
  23. -output OUTPUT        store text in this file (default inputfilename.txt)
  24. -grid GRID            merge lines if closer than this (default 2)
  25. -fontsize FONTSIZE    only include text with a larger fontsize (default 3)

Note

Command options may be abbreviated as long as no ambiguities are introduced. So the following do the same:

  • ... -output text.txt -noligatures -noformfeed -convert-white -grid 3 -extra-spaces ...

  • ... -o text.txt -nol -nof -c -g 3 -e ...

The output filename defaults to the input with its extension replaced by .txt. As with other commands, you can select page ranges (caution: 1-based!) in mutool format, as indicated above.

  • mode: (str) select a formatting mode – default is “layout”.

  • noligatures: (bool) corresponds to not TEXT_PRESERVE_LIGATURES. If specified, ligatures (present in advanced fonts: glyphs combining multiple characters like “fi”) are split up into their components (i.e. “f”, “i”). Default is passing them through.

  • convert-white: corresponds to not TEXT_PRESERVE_WHITESPACE. If specified, all white space characters (like tabs) are replaced with one or more spaces. Default is passing them through.

  • extra-spaces: (bool) corresponds to not TEXT_INHIBIT_SPACES. If specified, large gaps between adjacent characters will be filled with one or more spaces. Default is off.

  • noformfeed: (bool) instead of hex(12) (formfeed), write linebreaks \n at end of output pages.

  • skip-empty: (bool) skip pages with no text.

  • grid: lines with a vertical coordinate difference of no more than this value (in points) will be merged into the same output line. Only relevant for “layout” mode. Use with care: 3 or the default 2 should be adequate in most cases. If too large, lines that are intended to be different in the original may be merged and will result in garbled and / or incomplete output. If too low, artifact separate output lines may be generated for some spans in the input line, just because they are coded in a different font with slightly deviating properties.

  • fontsize: include text with fontsize larger than this value only (default 3). Only relevant for “layout” option.