RaspPi Vnc HowTo

5 Aug 2012

In a previous post, I demoed a setup that used VNC and a Raspberry Pi to produce a cheap and easy networked display. Commenters on the corresponding YouTube video have asked for more details on exactly how to do this, so here’s a step-by-step guide.

What You Need

Firstly, a Raspberry Pi. I’m using a standard-issue Model B (the only model available for purchase at time of writing). The RaspPi needs to be connected to the network; I’m using the built-in Ethernet adaptor; a USB WiFi adaptor should also work, but this is beyond the scope of these instructions. You’ll also need a mouse and keyboard to get things set up, but these are not needed for normal operation. This means you can borrow them from another machine, as opposed to buying new ones. You’ll also need a display, obviously; I’m assuming you’re using the HDMI connection.

Secondly, you’ll need an OS. These instructions are based on Raspian; you could do the same thing on other Linux distros, but the details will vary a lot, especially in terms of installing packages. I’m using the 2012-07-15 Wheezy image, downloaded from the Raspberry Pi downloads page - a more recent version should also be fine. The image, plus the modifications below, will fit on a 2GB SD card. You’ll find links to details on how to write the OS image to the SD card, and general setup instructions if you need them, on the download page.

Note that these instructions result in a setup where the RaspPi works only as a VNC client; in particular, you won’t easily be able to use a normal desktop. Fortunately, you can go back to a more “normal” Raspberry Pi experience just by swapping in another SD card with a more usual OS image on it.

Installing the software

On first boot, Raspbian presents you with a text menu containing the various options. Select the following ones (using the arrow keys and return/enter) and follow the instructions given:

  • expand_rootfs - this expands the file system so that it uses all of the available space on your SD card.
  • change_pass - it’s essential to change the password on any system that’s going to be accessed over the network.
  • ssh - enabling the ssh server isn’t essential, but it makes maintenance of the RaspPi easier once you’ve ditched the keyboard and mouse.
  • boot_behaviour - Answer yes to the question “Should we boot straight to desktop?” - we’ll be replacing the desktop with the VNC viewer.

When you’ve changed those options, press the escape key to exit the config menu; this will leave you at a command prompt.

Next, install the VNC viewer. Fortunately, Raspbian’s Debian heritage makes this part really easy. There’s a package for TightVNC, the VNC viewer we’re going to use, so installing it is just a matter of running the following command:

sudo apt-get install xtightvncviewer

apt-get will present you with a list of packages that need to be installed, and ask you if you want to continue. Type y, and it will install TightVNC and all of its dependencies.


In order to have the listening VNC viewer come up when the machine boots, we’re going to override the default behaviour of the desktop session. This is done by creating a file called .xsession in the default user’s home directory (/home/pi; this will be the current directory). If that file exists, it’s run (as a shell script) in place of the normal desktop session. The contents should be:

# Determine the IP address of the "eth0" network interface
export IP=`ip addr show eth0 | grep -oP '(?<=inet )(\d+\.){3}\d+'`

# Display the IP address, so people know where to connect
wish <<END &
pack [label .ip -text "$IP:5500" -font "Helvetica 72" -fg grey -bg black]

# Listen for VNC connections
xvncviewer -listen -fullscreen

(If you’re unsure as to how to create text files, try running nano .xsession editor on the command line.)

There’s quite a bit going on here. The last line is the easiest; this just runs the VNC viewer so that it listens for incoming connections, and uses full screen mode. The rest of the script finds the IP address that the RaspPi has been allocated, and displays a large banner showing the address and port that you need to use to connect VNC servers (for example, “”). It does this using wish, the windowing shell for Tcl/TK1.

Finally, we need to disable the screensaver and monitor power saving on the X server. To do this, you need to edit the LightDM config file2. Run sudo nano /etc/lightdm/lightdm.conf, find the lines:


and change them to read:

xserver-command=X -s 0 -dpms

That’s it; you can now reboot (sudo reboot from the command line, or just cut the power). You should see the startup messages scroll past, then a little while later the screen will clear and you’ll see the banner with the IP address and port.


Exactly how you do this depends on the platform from which you want to connect. If you already use a VNC server, it may well have some way to make reverse connections; check the documentation. If not, here’s how to get started:

  • Windows: Download and install RealVNC Open, and run the server. A small icon will appear in the system tray (at the right hand end of the taskbar). Right-click on this, select the “Add New Client” menu, and enter the IP address and port shown.

  • Mac OS X: There is a VNC server built in to OS X, but I’ve yet to find a way of making it perform reverse connections. As an alternative, download Vine VNC and put it in your Applications folder. Run it, select Reverse Connection from the Server menu, and enter the IP address (the default port is correct).

  • Linux: Install a VNC server via your package manager, then from within the VNC server (i.e., with $DISPLAY set to its display number) run vncconfig -connect <host>:<port>.

Odds & Ends

Firstly, a word about security, The setup, as described, doesn’t use any encryption for the VNC connection, so I’d only use this on a local network. In most cases (including a typical home router, and the majority of office networks), you need to take specific steps to expose a machine to the wider internet, so you almost certainly don’t need to worry about this. If you’re doing this at work, though, be sure to check with your network administrator first.

One thing you’ll notice is that the viewer doesn’t scale the desktop it’s displaying. If the desktop you connect is a lower resolution than the RaspPi display, it’ll be shown surrounded by a black border. If it’s higher resolution, you’ll only be able to see the top-left (unless you use the RaspPi’s mouse to pan around). For best results, make sure that the resolutions match3.

Performance will vary according to the network, but I’ve found it reasonable for general use. It’s not really up to video, but it should be fine for presentations.

Hopefully, this setup will prove useful; give it a go, and let me know.

Update: The above description originally used the port number 5550, whereas the default listening port is actually 5500. Thanks to Sergey Dobrodey for spotting this.

Update 2: Marc-André Gasser has spotted that the screen may blank after about 10 minutes; I think that this is due to a change in the default setup in newer Raspbian releases, but I may have simply missed it due to a quirk in my initial setup. In any case, Marc has found a solution. Add the following lines to /etc/X11/xinit/xinitrc, after the first line:

xset s off
xset -dpms
xset s noblank

This isn’t specific to the VNC server; it’s likely to be useful for any application that’s used as a permanent display. Thanks, Marc!

  1. I’d not recommend this as a way to create user interfaces in general. However, it’s convenient for one-liners like this, and it has the advantage of being installed alongside X Windows in most Linux distributions. [back]

  2. Thanks to Raspberry Pi forum member “wpc” for documenting this here. [back]

  3. Several VNC viewers provide desktop scaling, which would be ideal. However, I haven’t yet been able to get any of them working from .xsession in listen mode. If and when I do, I’ll post an update. [back]

This site is maintained by me, Rob Hague. The opinions here are my own, and not those of my employer or anyone else. You can mail me at rob@rho.org.uk, and I'm @robhague@mas.to on Mastodon and robhague on Twitter. The site has a full-text RSS feed if you're so inclined.

Body text is set in Georgia or the nearest equivalent. Headings and other non-body text is set in Cooper Hewitt Light. The latter is © 2014 Cooper Hewitt Smithsonian Design Museum, and used under the SIL Open Font License.

All content © Rob Hague 2002-2024, except where otherwise noted.