Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar
Find #mupdf on Discord
Do you have any feedback on this page?

# MuPDF on the command line

MuPDF has few command line options available:

- mupdf-gl A handy viewer UI.

- muraster Can be used to convert PDF pages to raster images.

- mutool An all purpose tool for dealing with PDF files. Used in conjunction with the mutool JavaScript API

## mupdf-gl

The OpenGL based viewer can read PDF, XPS, CBZ, EPUB, & FB2 documents as well as typical image formats including SVG. It compiles on any platform that has a GLUT library. The latest release builds on Linux, Windows, and MacOS.

### Command Line Options

    mupdf-gl [options] document [page]

`[options]`

> `-p` password

>   The password needed to open a password protected PDF file.

> `-c` profile.cc

>   Load an ICC profile to use for display (default is sRGB).

> `-r` resolution

>   Set the initial zoom level, specified as DPI. The default value is `72`.

> `-W` width

>   Set the page width in points for EPUB layout.

> `-H` height

>   Set the page height in points for EPUB layout.

> `-S` size

>   Set the default font size in points for EPUB layout.

> `-U` stylesheet

>   Specify a CSS file containing user styles to load for EPUB layout.

> `-X`

>   Ignore publisher styles for EPUB layout.

> `-J`

>   Disable JavaScript in PDF forms.

> `-A` level

>   Set anti-aliasing level or pixel rendering rule.

>   - `0`: off.

>   - `2`: 4 levels.

>   - `4`: 16 levels.

>   - `8`: 256 levels.

>   - `9`: using centre of pixel rule.

>   - `10`: using any part of a pixel rule.

> `-I`

>   Start in inverted color mode.

> `-B` hex-color

>   Set black tint color (default `303030`).

> `-C` hex-color

>   Set white tint color (default `FFFFF0`).

> `-Y` factor

>   Set UI scaling factor (default calculated from screen DPI).

`[page]`

  The initial page number to show.

Example usage #1:

This will open the viewer with a file browser which allows you to choose the file you need.

    mupdf-gl

Example usage #1:

This will open a specific file, in inverted color mode, on page 10.

    mupdf-gl -I mupdf_explored.pdf 10

### Mouse Bindings

The middle mouse button (scroll wheel button) pans the document view.

The right mouse button selects a region and copies the marked text to the clipboard.

### Key Bindings

Several commands can take a number argument entered before the key, to modify the command. For example, to zoom to 150 dpi, type “150z”.

F1 | Display help.
i | Show document information.
o | Show document outline.
L | Highlight links.
F | Highlight form fields.
a | Show annotation editor.
r | Reload document.
S | Save document (only for PDF).
q | Quit viewer.

< | Decrease E-book font size.
> | Increase E-book font size.
I | Toggle inverted color mode.
C | Toggle tinted color mode.
E | Toggle ICC color management.
e | Toggle spot color emulation.
A | Toggle anti-aliasing.

f | Toggle fullscreen.
w | Shrinkwrap window to fit page.
W | Fit page width to window.
H | Fit page height to window.
Z | Fit page size to window.
[number] z | Set zoom resolution in DPI.
+ | Zoom in.
- | Zoom out.
[ | Rotate counter-clockwise.
] | Rotate clockwise.
⬅️➡️⬆️⬇️ or h, j, k, l | Pan page in small increments.

b | Smart move one screenful backward.
[space] | Smart move one screenful forward.
[comma] or [page up] | Go one page backward.
[period] or [page down] | Go one page forward.
[number] g | Go to page number.
G | Go to last page.

m | Save current page to navigation history.
t | Go back in navigation history.
T | Go forward in navigation history.
[number] m | Save current page in numbered bookmark.
[number] t | Go to numbered bookmark.

/ | Start searching forward.
? | Start searching backward.
n | Continue searching forward.
N | Continue searching backward.

## muraster

This is a much simpler version of `mutool draw` command. As such it can be used to quickly rasterize an input file with a set of options.

### Command Line Options

    muraster [options] file [pages]

`[options]`

> `-p` password

>   The password needed to open a password protected PDF file.

> `-o` filename

>   The output file name.

> `-F` format

>   The output format (default inferred from output file name), e.g. `pam`, `pbm`, `pgm`, `pkm`, `ppm`.

> `-s` information

>   Show extra information: - `m`: show memory use. - `t`: show timings.

> `-R` rotation

>   Set a rotation for the output (default `auto`): - `auto`. - `0`. - `90`. - `180`. - `270`. - `clockwise`.

> `-r` x,y

>   Comma separated x and y resolution in DPI (default: 300,300).

> `-w` width

>   Printable width (in inches) (default: 8.27).

> `-h` height

>   Printable height (in inches) (default: 11.69).

> `-f`

>   Fit file to page if too large.

> `-B` height

>   Set the minimum band height (e.g. 32).

> `-M` memory

>   Sets the maximum band memory (e.g. 655360).

> `-W` width

>   Page width for EPUB layout.

> `-H` height

>   Page height for EPUB layout.

> `-S` size

>   Font size for EPUB layout.

> `-U` filename

>   File name of user stylesheet for EPUB layout

> `-X`

>   Disable document styles for EPUB layout

> `-A` level

>   Set anti-aliasing level.

>   - `0`: off.

>   - `2`: 4 levels.

>   - `4`: 16 levels.

>   - `8`: 256 levels.

> `-A` graphics level / text level

>   Independently set the anti-aliasing levels for graphics and text.

>   e.g. `-A 0/4`.

`[pages]`

  A comma separated list of page numbers and ranges.

Example usage #1:

This will render a raster file from page one of the input file “mupdf_explored.pdf”. The output file will be called “test.ppm”, have a clockwise rotation and specific graphics/text anti-aliasing applied.

    muraster -o test.ppm -R clockwise -A 0/8 mupdf_explored.pdf 1

## mutool

Note

It is advised to use rlwrap with `mutool` for command line history and cursor navigation (this can be also installed via Homebrew or MacPorts).

Note

Use `mutool -help` for summary usage.

For rendering and converting documents there are three commands available:

> - mutool draw

> This is the more customizable tool, but also has a more difficult set of command line options. It is primarily used for rendering a document to image files.

> - mutool convert

> This tool is used for converting documents into other formats, and is easier to use.

> - mutool trace

> This is a debugging tool used for printing a trace of the graphics device calls on a page.

There are also several tools specifically for working with PDF files:

> - mutool show

> A tool for displaying the internal objects in a PDF file.

> - mutool extract

> Extract images and embedded font resources.

> - mutool clean

> Rewrite PDF files. Used to fix broken files, or to make a PDF file human editable.

> - mutool merge

> Merge pages from multiple input files into a new PDF.

> - mutool poster

> Divide pages of a PDF into pieces that can be printed and merged into a large poster.

> - mutool create
>   - Page content streams

> Create a new PDF file from a text file with graphics commands.

> - mutool sign
>   - Signing
>     - Certificates
>     - Examples

> List, verify, and sign digital signatures in PDF files.

> - mutool info

> Prints details about objects on each page in a PDF file.

> - mutool pages

> Prints the size and rotation of each page in a PDF. Provides information about MediaBox, ArtBox, etc. for each page in a PDF file.

> - mutool trim

> This command allows you to make a modified version of a PDF with content that falls inside or outside of defined boxes removed.

> - mutool run
>   - JavaScript Shell
>   - Example scripts
>     - Create and edit PDF documents
>     - Graphics and the device interface
>     - Advanced examples

> A tool for running JavaScript programs with access to the MuPDF library functions.

> See the JavaScript API for more.

Do you have any feedback on this page?

This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at artifex.com or contact Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco, CA 94129, USA, for further information.