Setting up VNC on Raspberry Pi

Although the Raspberry Pi can be connected to a TV or monitor via HDMI or DVI, there are times when running a Raspberry Pi “headless” (without a monitor) is desirable. In a headless setup, you could connect to your Raspberry via SSH but if you want the full desktop then you will need to connect using a remote desktop protocol. The easiest is to setup VNC on Raspberry Pi. Virtual Network Computing (VNC) is a graphical desktop protocol that allows you to access the full Raspberry Pi desktop from another machine. Typically you would run the VNC client on a PC running Windows, OS X or Linux and access the Pi’s desktop over the network.

The first step is to install the VNC server on the Raspberry Pi. To do this, run the following command to install TightVNC, a lightweight and open-source implementation of the VNC system:

sudo apt-get install tightvncserver

Now that the server has been installed, it needs to be started to generate a remote desktop session. The server isn’t started by default however it can be started manually like this:

vncserver -geometry 1024x728 -depth 24

Where -geometry sets the resolution of the remote desktop, in this case 1024 x 768; and -depth sets the color depth, in this case 24 bits. The first time you run the VNC server you will be asked for a remote access password. This is the password that must be entered when someone tries to remotely connect to the desktop. This password shouldn’t be relied on as the sole means to stop public access to a remote desktop but on a private home or office network, it should be sufficient to limit access to the Pi’s user interface. You can change the password at any time using the vncpasswd tool.


As part of the output from the server, start up the vncserver will report the number of the virtual display it has created. Under X (the underlying system for many Linux windowing environments), you can have multiple displays with the default physical desktop being :0. The vncserver will likely create display :1 which can be accessed from a VNC client on port 5901. Port 5902 is for remote virtual desktop :2 and so on. You can force the VNC server to create a session on a certain display by specifying the number as the first parameter:

vncserver :1 -geometry 1024x728 -depth 24

You can kill a remote desktop at any time using:

vncserver -kill :1

Where :1 is the desktop number.

VNC clients

There are lots of VNC clients (often called VNC viewers) for Windows, OS X and Linux. You can get a Windows viewer from the TightVNC website and for Linux you can install one from your distro’s repository. For Ubuntu use:

sudo apt-get install vncviewer

To connect to the Raspberry Pi, start the VNC viewer:


Where is the address of the Raspberry Pi and :1 is the desktop number.

Start VNC server on boot

It is possible to get the VNC server to start at boot by creating a special initialization script. Create a file called vncserver in your home directory with the following shell code:

# Provides:          VNC
# Required-Start:    $local_fs
# Required-Stop:
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Start or stop the VNC server
eval cd ~pi
case "$1" in
        su pi -c "/usr/bin/vncserver :1 -geometry 1024x728 -depth 24"
        echo "Started VNC server."
        su pi -c "/usr/bin/vncserver -kill :1"
        echo "Stopped VNC server."
        echo "Usage: vncserver [start|stop]" >&2
        exit 3

Now run the following commands to change the owner of the file to root, copy it to the init.d directory and install the script:

sudo mv vncserver /etc/init.d/
sudo chown root:root /etc/init.d/vncserver
sudo chmod 755 /etc/init.d/vncserver
sudo update-rc.d vncserver defaults

Now reboot and check that the VNC server has been started automatically. There are a couple of things that you should note about this script. First it assumes that the you are using the default pi user and secondly, it will only work if you have previously set a password using vncpasswd or you have run the VNC server manually at least once.


Now that the VNC server is installed, you can get access to a full desktop over the network using a VNC client. Even if your Raspberry Pi is connected to a TV or monitor, it is a great way to enable remote administration of the device. If you ever need to stop the VNC server, you can now use the following command:

sudo service vncserver stop

It can also be started again by replacing the stop parameter with a start parameter.

Gary Sims

Gary has been a technical writer, author and blogger since 2003. He is an expert in open source systems (including Linux), system administration, system security and networking protocols. He also knows several programming languages, as he was previously a software engineer for 10 years. He has a Bachelor of Science in business information systems from a UK University.

Subscribe to our newsletter!

Our latest tutorials delivered straight to your inbox