man pages section 1: User Commands

Exit Print View

Updated: July 2014

vncviewer (1)


vncviewer - VNC viewer for X


/usr/bin/vncviewer [options] [host][:display#]
vncviewer [options] [host][::port]
vncviewer [options] -listen [port]


Virtual Network Computing                            vncviewer(1)

     vncviewer - VNC viewer for X

     /usr/bin/vncviewer [options] [host][:display#]
     vncviewer [options] [host][::port]
     vncviewer [options] -listen [port]

     vncviewer  is  a viewer (client) for Virtual Network Comput-
     ing.  This manual page documents version 4 for the X  window

     If  you  run the viewer with no arguments it will prompt you
     for a VNC server to connect to.  Alternatively, specify  the
     VNC server as an argument, e.g.:

          vncviewer snoopy:2

     where  'snoopy'  is  the name of the machine, and '2' is the
     display number of the VNC server on  that  machine.   Either
     the  machine  name or display number can be omitted.  So for
     example ":1" means display number 1 on the same machine, and
     "snoopy"   means   "snoopy:0"  i.e.  display  0  on  machine

     If the VNC server is successfully  contacted,  you  will  be
     prompted  for  a password to authenticate you.  If the pass-
     word is correct, a window will appear showing the desktop of
     the VNC server.

     The  viewer  tests the speed of the connection to the server
     and chooses the encoding  and  pixel  format  (color  level)
     appropriately.  This makes it much easier to use than previ-
     ous versions where the user had to  specify  arcane  command
     line arguments.

     The  viewer  normally  starts out assuming the link is slow,
     using the encoding with the best compression.  If  it  turns
     out  that the link is fast enough it switches to an encoding
     which compresses  less  but  is  faster  to  generate,  thus
     improving the interactive feel.

     The  viewer normally starts in full-color mode, but switches
     to low-color mode if the bandwidth is insufficient. However,
     this  only occurs when communicating with servers supporting
     protocol 3.8 or newer, since many old servers does not  sup-
     port color mode changes safely.

     Automatic  selection  can  be  turned  off  by  setting  the

TigerVNC             Last change: 05 May 2004                   1

Virtual Network Computing                            vncviewer(1)

     AutoSelect parameter to false, or from the options dialog.

     The viewer has a popup menu containing entries which perform
     various  actions.   It is usually brought up by pressing F8,
     but this can  be  configured  with  the  MenuKey  parameter.
     Actions which the popup menu can perform include:

       * switching in and out of full-screen mode

       * quitting the viewer

       * generating key events, e.g. sending ctrl-alt-del

       * accessing the options dialog and various other dialogs

     By  default,  key  presses in the popup menu get sent to the
     VNC server and dismiss the popup.  So to get an  F8  through
     to the VNC server simply press it twice.

     A  full-screen mode is supported.  This is particularly use-
     ful when connecting to a remote screen  which  is  the  same
     size  as your local one. If the remote screen is bigger, you
     can scroll by bumping the mouse  against  the  edge  of  the

     Unfortunately  this  mode  doesn't  work completely with all
     window managers, since it breaks  the  X  window  management

     You  can get a list of parameters by giving -h as a command-
     line option to vncviewer.  Parameters can be turned on  with
     -param  or off with -param=0.  Parameters which take a value
     can be specified as -param value.   Other  valid  forms  are
     param=value -param=value --param=value.  Parameter names are

     Many of the parameters can also be set graphically  via  the
     options  dialog  box.   This  can be accessed from the popup
     menu or from the "Connection details" dialog box.

     -display Xdisplay
          Specifies the X display on which the VNC viewer  window
          should appear.

TigerVNC             Last change: 05 May 2004                   2

Virtual Network Computing                            vncviewer(1)

     -geometry geometry
          Standard X position and sizing specification.

     -listen [port]
          Causes  vncviewer  to listen on the given port (default
          5500) for reverse connections from a VNC server.   Win-
          VNC  supports  reverse  connections initiated using the
          'Add New Client' menu option or the '-connect' command-
          line  option.  Xvnc supports reverse connections with a
          helper program called vncconfig.

     -passwd password-file
          If you are on a filesystem which gives  you  access  to
          the  password  file used by the server, you can specify
          it here to avoid typing it  in.   It  will  usually  be

          When  you  make a connection to a VNC server, all other
          existing connections are normally closed.  This  option
          requests  that they be left open, allowing you to share
          the desktop with someone already using it.

          Specifies that no keyboard or mouse  events  should  be
          sent to the server.  Useful if you want to view a desk-
          top without interfering; often  needs  to  be  combined
          with -Shared.

          Start in full-screen mode.

     -DesktopSize widthxheight
          Instead of keeping the existing remote screen size, the
          client will attempt to switch to  the  specified  since
          when  connecting.  If  the  server does not support the
          SetDesktopSize message then the screen will retain  the
          original size.

          Use  automatic  selection  of encoding and pixel format
          (default is on).  Normally the viewer tests  the  speed
          of  the connection to the server and chooses the encod-
          ing and pixel format appropriately.  Turn it  off  with

TigerVNC             Last change: 05 May 2004                   3

Virtual Network Computing                            vncviewer(1)

     -FullColor, -FullColour
          Tells  the  VNC server to send full-color pixels in the
          best format for this display.  This is default.

     -LowColorLevel, -LowColourLevel level
          Selects the reduced color level to use on  slow  links.
          level  can  range  from  0  to 2, 0 meaning 8 colors, 1
          meaning 64 colors (the default), 2 meaning 256  colors.
          Note  that  decision  if reduced color level is used is
          made by vncviewer. If you would like to force vncviewer
          to use reduced color level use -AutoSelect=0 parameter.

     -PreferredEncoding encoding
          This option specifies the  preferred  encoding  to  use
          from one of "Tight", "ZRLE", "hextile" or "raw".

          Render  the mouse cursor locally if the server supports
          it (default is on).  This can make the interactive per-
          formance feel much better over slow links.

     -WMDecorationWidth w, -WMDecorationHeight h
          The  total  width and height taken up by window manager
          decorations.  This is used  to  calculate  the  maximum
          size  of  the  VNC  viewer window.  Default is width 6,
          height 24.

     -log logname:dest:level
          Configures the debug log settings.  dest can  currently
          be  stderr  or  stdout, and level is between 0 and 100,
          100 meaning most verbose output.  logname is usually  *
          meaning  all, but you can target a specific source file
          if you know the name of its  "LogWriter".   Default  is

     -MenuKey keysym-name
          This option specifies the key which brings up the popup
          menu.  The key is  specified  as  an  X11  keysym  name
          (these  can be obtained by removing the XK_ prefix from
          the   entries    in    "/usr/include/X11/keysymdef.h").
          Default is F8.

     -via gateway
          Automatically  create encrypted TCP tunnel to the gate-
          way machine before  connection,  connect  to  the  host

TigerVNC             Last change: 05 May 2004                   4

Virtual Network Computing                            vncviewer(1)

          through  that  tunnel  (TigerVNC-specific). By default,
          this option invokes SSH local port forwarding, assuming
          that SSH client binary can be accessed as /usr/bin/ssh.
          Note that when using the -via option, the host  machine
          name  should  be  specified  as  known  to  the gateway
          machine, e.g.  "localhost" denotes the gateway, not the
          machine  where  vncviewer was launched. The environment
          variable VNC_VIA_CMD can override  the  default  tunnel
          command                                              of
          /usr/bin/ssh -f -L "$L":"$H":"$R" "$G" sleep 20.    The
          tunnel  command  is executed with the environment vari-
          ables L, H, R, and G taken the values of the local port
          number,  the remote host, the port number on the remote
          host, and the gateway machine respectively.

     Xvnc(1), vncpasswd(1), vncconfig(1), vncserver(1)

     Tristan Richardson, RealVNC Ltd.

     VNC was originally developed by the RealVNC  team  while  at
     Olivetti   Research   Ltd  /  AT&T  Laboratories  Cambridge.
     TightVNC additions were implemented by Constantin Kaplinsky.
     Many  other  people participated in development, testing and

     See  attributes(5)  for  descriptions   of   the   following

     |      ATTRIBUTE TYPE         |         ATTRIBUTE VALUE           |
     |Availability                 |desktop/remote-desktop/tigervnc    |
     |Interface Stability          |Path: Committed, Options: Volatile |

TigerVNC             Last change: 05 May 2004                   5