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  software.)   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 de-
       tails.

OPTIONS
       The following command line options are available.  All command line op-
       tions 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 running, 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
              except  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
              option  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 percent-
              age,  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).  [con-
              fig file: textEncoding]

       -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
              section.

       -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  com-
              mands.  [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
              selection 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 sensi-
              tive,  smart case (case sensitive only if the search string con-
              tains uppercase characters), find whole words.

   Menu bar
       The menu bar is above the toolbar.  The menu items should  be  self-ex-
       planatory.

   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
       select 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  attach-
       ments.

   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 selection.

       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 selec-
       tion.

       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 buf-
       fer.

   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
       another 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  win-
              dow.

       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 previ-
              ous page.

       control-<PageUp> or control-<up-arrow>
              Go to the previous page.  If <ScrollLock> is active, this  main-
              tains 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
       unbind 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  charac-
       ters  (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 sim-
              ple 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  clip-
              board.

       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 se-
              lection.  (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
              session file is specified  with  the  sessionFile  setting  (see
              xpdfrc(5)).

       loadTabState
              Load  the tab state file (which was written via the saveTabState
              command), and restore the tabs listed in that  file.   The  path
              for  the  tab state file is specified with the tabStateFile set-
              ting (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 speci-
              fied 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 password.  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 exam-
              ple:
              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.  Lo-
              cation 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 win-
              dow 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  posi-
              tion.

       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
              specific  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 num-
              ber (on separate lines).  This file can be loaded later with the
              loadTabState command.  The path for the tab state file is speci-
              fied with the tabStateFile 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
              horizontal 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
              movement.

       scrollToRightEdge
              Scroll  to  the right edge of the current page, with no vertical
              movement.

       scrollToTopEdge
              Scroll to the top edge of the first displayed page, with no hor-
              izontal 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 appropri-
              ate.

       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
              extending 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
              extended 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
              numbers.

       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  COM-
       MANDS section).  Subsequent invocations of "xpdf -remote" with the same
       remote server name will send commands to the  already-running  instance
       of  xpdf.  The "checkOpenFile" commands are useful here for things like
       changing pages.  For example:

                  # 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
              reopen
                  # 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)
