FreeBSD Manual Pages
xpdf(1) General Commands Manual xpdf(1) NAME xpdf - Portable Document Format (PDF) file viewer (version 4.06) SYNOPSIS xpdf [options] [PDF-file [:page | +dest]] ... xpdf [options] -remote remote-name [command ...] xpdf [options] -open [PDF-file] DESCRIPTION Xpdf is a viewer for Portable Document Format (PDF) files. (These are also sometimes also called 'Acrobat' files, from the name of Adobe's PDF soft- ware.) Xpdf uses the Qt GUI toolkit and runs on Unix, OS X, and Windows. To run xpdf, type: xpdf file.pdf where file.pdf is your PDF file. The file name can be followed by a page number to be displayed, prefixed with a colon: xpdf file.pdf :18 or by a named destination, prefixed with '+' (this is only useful with PDF files that provide named destination targets): xpdf file.pdf +destinationA If you specify multiple files, they will each be opened in a separate tab: xpdf file1.pdf file2.pdf :18 file3.pdf You can also start xpdf without opening any files: xpdf CONFIGURATION FILE Xpdf reads a configuration file at startup. It first tries to find the user's private config file, ~/.xpdfrc. If that doesn't exist, it looks for a system-wide config file, typically /etc/xpdfrc (but this location can be changed when xpdf is built). See the xpdfrc(5) man page for details. OPTIONS The following command line options are available. All command line options must come before any PDF files to be opened. Many of the options can be set with configuration file commands. These are listed in square brackets with the description of the corresponding command line option. -geometry geometry Set the initial window geometry. -title title Set the window title. By default, the title will be "xpdf: foo.pdf". -open [PDF-file] This option sets up a default remote server. If Xpdf is already running (with the "-open" switch), the PDF file (if any) is opened in a new tab. If Xpdf (with the "-open" switch) is not already run- ning, starts Xpdf and opens the PDF file (if any). This is useful for GUI desktop environments, e.g., the typical double-click on a PDF file case. -rv Set reverse video mode. This reverses the colors of everything ex- cept images. It may not always produce great results for PDF files which do weird things with color. This also causes the paper color to default to black. -papercolor color Set the "paper color", i.e., the background of the page display. The color can be #RRGGBB (hexadecimal) or a named color. This op- tion will not work well with PDF files that do things like filling in white behind the text. [config file: paperColor] -mattecolor color Set the matte color, i.e., the color used for background outside the actual page area. The color can be #RRGGBB (hexadecimal) or a named color. [config file: matteColor] -fsmattecolor color Set the matte color for full-screen mode. The color can be #RRGGBB (hexadecimal) or a named color. [config file: fullScreenMatteColor] -z zoom Set the initial zoom factor. A number specifies a zoom percentage, where 100 means 72 dpi. You may also specify 'page', to fit the page to the window size, or 'width', to fit the page width to the window width. [config file: initialZoom] -rot angle Rotate pages by 0 (the default), 90, 180, or 270 degrees. -aa yes | no Enable or disable font anti-aliasing. This defaults to "yes". [config file: antialias] -aaVector yes | no Enable or disable vector anti-aliasing. This defaults to "yes". [config file: vectorAntialias] -enc encoding-name Sets the encoding to use for text output. The encoding-name must be defined with the unicodeMap command (see xpdfrc(5)). This defaults to "Latin1" (which is a built-in encoding). [config file: textEn- coding] -pw password Specify the password for the PDF file. This can be either the owner password (which will bypass all security restrictions) or the user password. -fullscreen Open xpdf in full-screen mode, useful for presentations. -remote remote-name Start Xpdf in remote server mode. See the REMOTE SERVER MODE sec- tion. -display display Set the X display (only available with X11). -cmd Print commands as they're executed (useful for debugging). [config file: printCommands] -tabstate tabstate-file Sets the file used by the loadTabState and saveTabState commands. [config file: tabStateFile] -cfg config-file Read config-file in place of ~/.xpdfrc or the system-wide config file. -v Print copyright and version information. -h Print usage information. (-help and --help are equivalent.) CONTROLS Toolbar toggle sidebar button Toggles (i.e., shows or hides) the sidebar. status indicator This icon is animated while Xpdf is rendering a page. It turns red when an error or warning has been issued. Clicking on it opens the error dialog. selection mode This icon is an "I-beam" in linear selection mode, and an arrow in block selection mode. Clicking on it toggles between the two selec- tion modes. page number entry box Move to a specific page number. Click in the box to activate it, type the page number, then hit return. This will instead display and accept page labels, if the "view - page labels" menu item is checked. left/right arrow buttons Go backward or forward along the history path. zoom out/in buttons Zoom out or in (i.e., change magnification) incrementally. zoom popup menu Change the zoom factor (see the description of the -z option above). fit width button Change the zoom factor to fit the page width to the window width. fit page button Change the zoom factor to fit the page to the window size. find entry box Find a text string. Click in the box to activate it, type a search string, then hit return. find next button Find the next occurrence of the search string. find previous button Find the previous occurrence of the search string. find settings button Display the current find settings: case insensitive, case sensitive, smart case (case sensitive only if the search string contains upper- case characters), find whole words. Menu bar The menu bar is above the toolbar. The menu items should be self-explana- tory. Tab list The tab list is on the left, just below the toolbar. It lists all open tabs. Outline/layers/attachments pane This pane is on the left, below the tab list. The popup allows you to se- lect from outline, layers, or attachments. The outline is a tree-like structure of bookmarks that allows moving within the PDF file. Not all PDF files have outlines. Layers (a.k.a. optional content) allow parts of the PDF content to be shown or hidden. Not all PDF files have layers. Attachments are other files embedded within the PDF file. There is a 'save' button for each attached file. Not all PDF files have attachments. Text selection In block selection mode, dragging the mouse with the left button held down will highlight an arbitrary rectangle. Shift-clicking will extend the se- lection. In linear selection mode, dragging with the left button will highlight text in reading order. Double-clicking or triple-clicking will select a word or a line, respectively. Shift-clicking will extend the selection. Selected text can be copied to the clipboard (with the edit/copy menu item). On X11, selected text will be available in the X selection buffer. Links When the mouse is over a hyperlink, the link target will be shown in a popup near the bottom of the window. Clicking on a hyperlink will jump to the link's destination. A link to an- other PDF document will make xpdf load that document. A 'launch' link to an executable program will display a dialog, and if you click 'ok', execute the program. URL links are opened in a system-dependent way. (On UNIX, Qt uses the $BROWSER environment variable.) Mouse bindings The left mouse button is used to select text (see above). Clicking on a link with the middle button opens the link in a new tab. Dragging the mouse with the middle button held down pans the window. The right mouse button opens a popup menu (see popupMenuCmd in xpdfrc(5)). Key bindings This section lists the default key bindings. Bindings can be changed using the config file (see xpdfrc(5)). control-o Open a new PDF file via a file requester. control-r Reload the current PDF file. Note that Xpdf will reload the file automatically (on a page change or redraw) if it has changed since it was last loaded. control-f Find a text string. This sets keyboard focus to the 'find' box. control-G Find next occurrence. control-C Copy selected text to the clipboard. control-P Print. control-0 (control-zero) Set the zoom factor to 125%. control-+ (control-plus) Zoom in (increment the zoom factor by 1). control-- (control-minus) Zoom out (decrement the zoom factor by 1). control-s Save PDF via a file requester. control-t Open a new tab. control-n Open a new window. control-w Close the current tab. Closes the window if this was the last open tab. Quits the application if this was the last open window. control-l Toggle between full-screen and window modes. control-q Quit. control-<tab> Next tab. control-shift-<tab> Previous tab. control-? Help. alt-<left-arrow> Go backward along the history path. alt-<right-arrow> Go forward along the history path. home Go to the top left of current page. control-<home> Go to the first page. end Go to the bottom right of current page. control-<end> Go to the last page. <space> or <PageDown> Scroll down on the current page; if already at bottom, move to next page. control-<PageDown> or control-<down-arrow> Go to the next page. If <ScrollLock> is active, this maintains the relative position on the page. <PageUp> Scroll up on the current page; if already at top, move to previous page. control-<PageUp> or control-<up-arrow> Go to the previous page. If <ScrollLock> is active, this maintains the relative position on the page. <esc> Exit full-screen mode. arrows Scroll the current page. g Set keyboard focus to the page number entry box. z Set the zoom factor to 'page' (fit page to window). w Set the zoom factor to 'width' (fit page width to window). Full-screen mode Xpdf can be placed into full-screen mode via the -fullscreen command line option, the 'full screen' menu item, or a binding to the fullScreenMode or toggleFullScreenMode command. Entering full-screen mode automatically switches to single-page view mode and to the fit-page zoom factor. Full-screen mode can be exited via the default <esc> key binding, or via a binding to the windowMode or toggleFullScreenModecommand. COMMANDS Xpdf's key and mouse bindings are user-configurable, using the bind and un- bind commands in the config file (see xpdfrc(5)). The bind command allows you to bind a key or mouse button to a sequence of one or more commands. In commands that take arguments (inside parentheses), special characters (namely '(', ')', ',', and '\x01') can be escaped by preceding them with a '\x01' character. This is mostly useful in things like scripts that need to be able to open arbitrary PDF files, using the 'openFile' command. The following commands are supported: about Open the 'about' dialog. blockSelectMode Set block selection mode. In this mode, the selection is a simple rectangle. Any part of the page can be selected, regardless of the content on the page. checkOpenFile(file) Check that file is open in the current tab, and open it if not. checkOpenFileAtDest(file,dest) Check that file is open in the current tab, and open it if not. In either case go to the specified named destination. checkOpenFileAtPage(file,page) Check that file is open in the current tab, and open it if not. In either case go to the specified page. closeSidebar Close the sidebar. closeSidebarMoveResizeWin Close the sidebar, resizing the window so that the document size doesn't change, and moving the window so that the document stays in the same place on the screen. closeSidebarResizeWin Close the sidebar, resizing the window so that the document size doesn't change. closeTabOrQuit Close the tab. If this was the last open tab, close the window. If this was the last window open, quit. closeWindowOrQuit Close the window. If this was the last open window, quit. continuousMode Switch to continuous view mode. copy Copy selected text to the clipboard. copyLinkTarget Copy the target of the link under the mouse cursor to the clipboard. endPan End a pan operation. endSelection End a selection. expandSidebar(n) Expand the sidebar by n pixels. Opens the sidebar if it is cur- rently closed. find Set keyboard focus to the 'find' box. findFirst Find the first occurrence of the search string. findNext Find the next occurrence of the search string. findPrevious Find the previous occurrence of the search string. focusToDocWin Set keyboard focus to the main document window. focusToPageNum Set keyboard focus to the page number text box. followLink Follow a hyperlink (does nothing if the mouse is not over a link). followLinkInNewTab Follow a hyperlink, opening PDF files in a new tab (does nothing if the mouse is not over a link). For links to non-PDF files, this command is identical to followLink. followLinkInNewTabNoSel Same as followLinkInNewTab, but does nothing if there is a non-empty selection. (This is useful as a mouse button binding.) followLinkInNewWin Follow a hyperlink, opening PDF files in a new window (does nothing if the mouse is not over a link). For links to non-PDF files, this command is identical to followLink. followLinkInNewWinNoSel Same as followLinkInNewWin, but does nothing if there is a non-empty selection. (This is useful as a mouse button binding.) followLinkNoSel Same as followLink, but does nothing if there is a non-empty selec- tion. (This is useful as a mouse button binding.) fullScreenMode Go to full-screen mode. goBackward Move backward along the history path. goForward Move forward along the history path. gotoDest(dest) Go to a named destination. gotoLastPage Go to the last page in the PDF file. gotoPage(page) Go to the specified page. help Open the help URL. hideMenuBar Hide the menu bar. hideToolbar Hide the toolbar. horizontalContinuousMode Switch to horizontal continuous view mode. linearSelectMode Set linear selection mode. In this mode, the selection follows text. Non-text regions cannot be selected. loadSession Load the session from the session save file. The path for the ses- sion file is specified with the sessionFile setting (see xpdfrc(5)). loadTabState Load the tab state file (which was written via the saveTabState com- mand), and restore the tabs listed in that file. The path for the tab state file is specified with the tabStateFile setting (see xpdfrc(5)). newTab Open an empty new tab. newWindow Open an empty new window. nextPage Go to the next page. nextPageNoScroll Go to the next page, with the current relative scroll position. nextTab Switch to the next tab. normalVideoMode Switch to normal video mode (the opposite of reverse video mode). open Open a PDF file in the current tab, using the open dialog. openErrorWindow Open the error window. openFile(file) Open the specified file in the current tab. openFile2(file,page,dest,passwd,location) Open the specified file. If dest is not empty, go to the specified named destination. Else, if page is not empty, go to the specified page number. If password is not empty, it is used as the PDF pass- word. If location is "win", open the file in a new window; if it is "tab", open in a new tab; if it is "check", open in the current tab, but only if the specified PDF file isn't already open; else open in the current tab. Any/all of the arguments, other than file, can be empty strings. For example: openFile2(test.pdf,7,,,tab) openFileAtDest(file,dest) Open the specified file in the current tab at the specified named destination. openFileAtDestIn(file,dest,location) Open the specified file at the specified named destination. Loca- tion must be "win" for a new window or "tab" for a new tab. openFileAtPage(file,page) Open the specified file in the current tab at the specified page. openFileAtPageIn(file,page,location) Open the specified file at the specified page. Location must be "win" for a new window or "tab" for a new tab. openFileIn(file,location) Open the specified file. Location must be "win" for a new window or "tab" for a new tab. openIn(location) Open a PDF file, using the open dialog. Location must be "win" for a new window or "tab" for a new tab. openSidebar Open the sidebar. openSidebarMoveResizeWin Open the sidebar, resizing the window so that the document size doesn't change, and moving the window so that the document stays in the same place on the screen. openSidebarResizeWin Open the sidebar, resizing the window so that the document size doesn't change. pageDown Scroll down by one screenful. pageUp Scroll up by one screenful. postPopupMenu Display the popup menu. prevPage Go to the previous page. prevPageNoScroll Go to the previous page, with the current relative scroll position. prevTab Switch to the previous tab. print Open the 'print' dialog. quit Quit from xpdf. raise Bring the xpdf window to the front. reload Reload the current PDF file. reverseVideoMode Switch to reverse video mode. rotateCCW Rotate the page 90 degrees counterclockwise. rotateCW Rotate the page 90 degrees clockwise. run(external-command-string) Run an external command. The following escapes are allowed in the command string: %f => PDF file name (or an empty string if no file is open) %b => PDF file base name, i.e., file name minus the extension (or an empty string if no file is open) %u => link URL (or an empty string if not over a URL link) %p => current page number (or an empty string if no file is open) %x => selection upper-left x coordinate (or 0 if there is no selection) %y => selection upper-left y coordinate (or 0 if there is no selection) %X => selection lower-right x coordinate (or 0 if there is no selection) %Y => selection lower-right y coordinate (or 0 if there is no selection) %t => selected text (limited to 500 characters) %i => page containing the mouse pointer %j => x coordinate of the mouse pointer %k => y coordinate of the mouse pointer %% => % The external command string will often contain spaces, so the whole command must be quoted in the xpdfrc file: bind x "run(ls -l)" The command string may not be run through a shell. It is recom- mended to keep the command simple, so that it doesn't depend on spe- cific shell functionality. For complex things, you can have the command string run a shell script. saveAs Save PDF via a file requester. saveImage Open the 'save image' dialog. saveSession Save the current session, consisting of all open windows and tabs, to the session save file. This file can be loaded later with the loadSession command. The path for the session file is specified with the sessionFile setting (see xpdfrc(5)). saveTabState Save a list of all tabs open in this window to the tab state file. For each tab, this writes the PDF file name and page number (on sep- arate lines). This file can be loaded later with the loadTabState command. The path for the tab state file is specified with the tab- StateFile setting (see xpdfrc(5)). scrollDown(n) Scroll down by n pixels. scrollDownNextPage(n) Scroll down by n pixels, moving to the next page if appropriate. scrollLeft(n) Scroll left by n pixels. scrollOutlineDown(n) Scroll the outline down by n increments. scrollOutlineUp(n) Scroll the outline up by n increments. scrollRight(n) Scroll right by n pixels. scrollToBottomEdge Scroll to the bottom edge of the last displayed page, with no hori- zontal movement. scrollToBottomRight Scroll to the bottom-right corner of the last displayed page. scrollToLeftEdge Scroll to the left edge of the current page, with no vertical move- ment. scrollToRightEdge Scroll to the right edge of the current page, with no vertical move- ment. scrollToTopEdge Scroll to the top edge of the first displayed page, with no horizon- tal movement. scrollToTopLeft Scroll to the top-left corner of the first displayed page. scrollUp(n) Scroll up by n pixels. scrollUpPrevPage(n) Scroll up by n pixels, moving to the previous page if appropriate. selectLine Set the selection to the line at the current mouse position. selectWord Set the selection to the word at the current mouse position. setSelection(pg,ulx,uly,lrx,lry) Set the selection to the specified coordinates on the specified page. showAttachmentsPane Shows the attachments in the outline/layers/attachments pane. showDocumentInfo Open the document information dialog. showKeyBindings Open the key bindings dialog. showLayersPane Shows the layers in the outline/layers/attachments pane. showMenuBar Show the menu bar. showOutlinePane Shows the outline in the outline/layers/attachments pane. showToolbar Show the toolbar. shrinkSidebar(n) Shrink the sidebar by n pixels. Closes the sidebar if shrinking it would go below the minimum allowed side. sideBySideContinuousMode Switch to side-by-side continuous view mode. sideBySideSingleMode Switch to side-by-side two-page view mode. singlePageMode Switch to single-page view mode. startExtendedSelection Extend the selection to the current mouse position, and continue ex- tending as the mouse moves. startPan Start a pan operation at the current mouse position, which will scroll the document as the mouse moves. startSelection Start a selection at the current mouse position, which will be ex- tended as the mouse moves. toggleContinuousMode Toggle between continuous and single page view modes. toggleFullScreenMode Toggle between full-screen and window modes. toggleMenuBar Toggle the menu bar between shown and hidden. toggleReverseVideoMode Toggle between reverse and normal video modes. toggleSelectMode Toggle between block and linear selection mode. toggleSidebar Toggle the sidebar between open and closed. toggleSidebarMoveResizeWin Toggle the sidebar between open and closed, resizing the window so that the document size doesn't change, and moving the window so that the document stays in the same place on the screen. toggleSidebarResizeWin Toggle the sidebar between open and closed, resizing the window so that the document size doesn't change. toggleToolbar Toggle the toolbar between shown and hidden. viewPageLabels Show page labels (if the PDF file has them), rather than page num- bers. viewPageNumbers Show page numbers, rather than page labels. windowMode Go to window (non-full-screen) mode. zoomFitPage Set the zoom factor to fit-page. zoomFitWidth Set the zoom factor to fit-width. zoomIn Zoom in - go to the next higher zoom factor. zoomOut Zoom out - go the next lower zoom factor. zoomPercent(z) Set the zoom factor to z%. zoomToSelection Zoom to the current selection. REMOTE SERVER MODE Starting xpdf with the "-remote" switch puts it into remote server mode. All remaining command line options are commands (see the COMMANDS section). Subsequent invocations of "xpdf -remote" with the same remote server name will send commands to the already-running instance of xpdf. The "check- OpenFile" commands are useful here for things like changing pages. For ex- ample: # Start up xpdf, and open something.pdf. xpdf -remote foo 'openFile(something.pdf)' # Switch to page 7 in the already-open something.pdf. If the user # has closed xpdf in the meantime, this will restart it and re- open # the file. xpdf -remote foo 'checkOpenFileAtPage(something.pdf, 7)' # Pass two commands to the remote instance: (1) open some- thing.pdf # and then (2) raise the xpdf window. xpdf -remote foo 'openFile(something.pdf)' raise EXIT CODES The Xpdf tools use the following exit codes: 0 No error. 1 Error opening a PDF file. 2 Error opening an output file. 3 Error related to PDF permissions. 99 Other error. AUTHOR The xpdf software and documentation are copyright 1996-2025 Glyph & Cog, LLC. SEE ALSO pdftops(1), pdftotext(1), pdftohtml(1), pdfinfo(1), pdffonts(1), pdfde- tach(1), pdftoppm(1), pdftopng(1), pdfimages(1), xpdfrc(5) http://www.xpdfreader.com/ 14 Nov 2025 xpdf(1)
NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION FILE | OPTIONS | CONTROLS | Full-screen mode | COMMANDS | REMOTE SERVER MODE | EXIT CODES | AUTHOR | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=xpdf&sektion=1&manpath=FreeBSD+15.1-RELEASE+and+Ports>