Setting-Up Raspberry Pi for Headless Mode with X11VNC

If you own a Raspberry Pi and want to use it in “headless” mode (without a display) you’ll probably want more than just an SSH command shell to administer it.

Many people install TightVNC however this doesn’t provide connectivity to the root display interface, only to virtual secondary interfaces. Only the root interface behaves like a real remote control session. And there are limitations of the secondary interfaces, e.g. you cannot connect before a user has logged on and the desktop has been loaded.

After a searching around a bit I found a better solution which provides root display connectivity called X11VNC. Here is how you install and configure it:

  1. Logon as the default user “pi”.
  2. Download and install X11VNC using the following command:[code]sudo apt-get install x11vnc[/code]
  3. Set the password required for VNC clients to connect by entering the following command. It’s important you do NOT run this command elevated (do not use sudo) because it writes the encrypted password in the current user’s home directory, which must be the default user if you want to connect before logon and desktop start-up:[code]x11vnc -storepasswd[/code]
  4. Create/edit the VNC start-up configuration file, stored in your home directory:[code]nano ~/.xsessionrc[/code]
  5. Enter/edit the text as follows:[code]# Start X11VNC
    x11vnc -bg -nevershared -forever -tightfilexfer -usepw -display :0[/code]
  6. Press CTRL+O then ENTER to write (save) the file then CTRL+X to exit.
  7. Make the file executable:[code]chmod 775 ~/.xsessionrc[/code]
  8. Edit the Raspberry Pi boot configuration to set HDMI as the standard output and set the default resolution, used when no physical display is detected. If you do not do this the default is the analogue output which is an extremely low resolution.[code]sudo nano /boot/config.txt[/code]
  9. Set the following line to force HDMI to be the only detected connection, i.e. disable the analogue video default:[code]hdmi_force_hotplug=1[/code]
  10. Set the HDMI “group” and “mode” number to select the default resolution. You can find these codes on Wikipedia or internet searches. To start with, a couple of useful modes:
    1. SVGA 1024×768@60Hz:[code]hdmi_group=2
    2. Full HD 1920×1080@60Hz:[code]hdmi_group=2
  11. There are other useful settings here you may wish to play with, such as overscan and CPU overclocking. 800Mhz works well, at least with my board which has custom heat sinks stuck on top of the three main chips.
  12. Press CTRL+O then ENTER to write (save) the file then CTRL+X to exit.
  13. Reboot:[code]sudo reboot[/code]
  14. Test connectivity with any VNC client, e.g. TightVNC client (even though the server does not satisfy our needs it’s still a great client).
  15. Power-off and disconnect the monitor. Power-on and after a few seconds you should still be able to connect via VNC with the correct display resolution.

Running a Raspberry Pi in headless mode really demonstrates the power of these little devices. You can hide them away with no monitor or keyboard, just provide a little power and network connectivity.


Add a USB wireless adapter to eliminate the network cable. Add a battery pack to go mobile. You can run them anywhere, even on the go! I’d recommend setting-up headless mode even if you don’t plan to use it immediately. Because it also provides a great way to quickly get GUI access from your other systems. You can even download VNC clients for mobile phones, allowing you to fully control them from anywhere.

21 thoughts on “Setting-Up Raspberry Pi for Headless Mode with X11VNC

  1. Mine didn’t work. everything went well until I rebooted. No errors on boot, although I dont see anything about “x11vnc” either.

    When I run the x11vnc manually after logging in as user pi I get a warning that I don’t have a password set, but I followed the -storepasswd promts without issue.

    After that warning I get:

    “XOpenDisplay(“”) failed.”

    Trying again with XAUTHLOCALHOSTNAME=localhost …

    *** XOpenDisplay failed. No -display or DISPLAY.
    *** Trying “:0” in 4 seconds. Press Ctrl-C to abort.
    *** 1 2 3 4
    XOpenDisplay(“:0”) failed.
    Trying again with XAUTHLOCALHOSTNAME=localhost …
    XOpenDisplay(“:0”) failed.
    Trying again with unset XAUTHLOCALHOSTNAME …

    *** XOpenDisplay failed (:0)

    Then there are some “tips and guidelines”

    Any ideas what is going wrong?

    1. The easiest mistake to make is not running commands with or without SUDO (user elevation). Most important is to run the storepasswd command in the same context (default “pi” user) as when it is launched at start-up, because it’s stored in the home path of whatever it runs as (not sudo/root user).
      The HDMI settings afterwards were to get around another issue where no display is detected in headless mode, which could be the other cause. But that was more than a physical thing (HDMI not working when plugged in later) than X11VNC thing when I tested. By fixing the HDMI settings you are telling the PI that it should just assume HDMI is present and not try to work with the analogue connector.
      Also make sure you use the raspi-config tool to set the desktop to auto-start.

      1. I believe I ran the storepasswd command as the user “pi” which, as far as I know, is the only user I have ever used. SSH commands still run as user “pi” correct? The terminal always had “pi@raspberry ~ $” on the left on both the USB keyboard and in the SSH terminal.

        My HDMI was connected, are you saying I should disconnect it for testing? I plan to run headless but I didn’t think having a monitor for testing would hurt. Please advise.

        I did not have the Pi setup to boot to desktop. Is that the major problem?

        Thanks for the help!

      2. I set the config to go to the desktop. That loads fine, but when I try to use TightVNC Viewer I am denied access.

        Then I ran x11vnc in ssh and it gave me A LOT of errors like this:

        rfbListenOnTCP6Port: error in bind IPv6 socket: Address family not supported by protocol

        Then I get this:

        Failure autoprobing: Address family not supported by protocol

        Then I get a lot of lines stating, what I can only describe as “**** it, we are going to try everything we have.”

        In those lines is an IP address that is slightly different from mine, and the statement “you are running x11vnc without a password” which sucks.

        the whole time I had HDMI connected to the Pi. Also when the pi does boot up it is not the Full HD that was indicated in /boot/config.txt it is much lower def. When I ran the Pi Store it was cut off, and there were no scroll bars on the right or bottom. So that piece doesn’t seem to work either.


      3. OK then that was the problem, the desktop must be running. Because VNC only remotes the graphics, in Linux remote access to the command line (if you don’t load the desktop) is done via a SSH. By the way I’d recommend Bitvise SSH Client for that.

        Anyway to get VNC working, just run raspi-config and switch the desktop auto-start option on, reboot then if everything else is correct it should work a few seconds after booting (as soon as the desktop appears). If that still fails then maybe it’s best to re-write the SD card and try again from scratch.

        My Raspberry Pi is tied-up right now as a server but I’m planning to free it up or buy another. When I do that I’ll re-visit these instructions to make sure nothing has been broken on current images/package updates.

        I’m also looking at a better solution using a different (non-desktop) start-up mechanism (init.d) for my BeagleBone Black. If/when that works I’ll come back here and update the instructions for the Pi too because I think that method is better and should work (with slight modifications for each specific Linux version) on all devices.

  2. Very good and clear instructions! Thanks!

    A couple of things though:
    1) What magic makes .xsession.rc run automatically? It didn’t for me, I had to run the script manually. With TightVNC I use a script in /etc/init.d, etc.

    2) Although happy with TightVNC, I tried x11vnc hoping that raspistill preview would show up in the vnc window – as it latches on session 0. It doesn’t, still only appears on the real monitor. This prevents seeing the previews in headless mode. I don’t know how to get that and I’m still looking. That would help when adjusting the camera for time-lapse photography for example. Right now I connect with bVNC Free over USB tethering and it works a treat – except the previews…

    If you know a trick for 2) drop me an email, you would made my day.

    One thing that made me revert back to TightVNC was that keeping left/right arrows pressed didn’t move the cursor more than one character. I’m used to keeping the arrow keys pressed until I get to the desired position. As well, it appeared somewhat sluggish compared with TightVNC.

    In any case, I’m quite happy with your instructions because I had to experiment with 2) and it saved me googling time for good advice on the setup.

    1. Raspistill previews come DIRECTLY from the GPU, and not software. The OS doesn’t see or control the overlays, so X11 can’t capture them. There isn’t a piece of remote control software that will be able to do that.

  3. I have to manually config mine to “accept connections” everytime it reboots which makes a headless startup impossible toi connect to. The program is is in the startup folder. Is there any syntax to put in the starup file to automatically set “accept connections”?

  4. Here is my start up file:
    [Desktop Entry]
    Exec=x11vnc -display :0 -forever -geometry 1920×1080 -ultrafilexfer

  5. Hi there – thanks for this, very useful info. Are there a list of other values for hdmi_group and hdmi_mode I can specify? I set those for 1024×768, but got 1184×624 – better than the 641×424 (or something) I was getting previously, but I’d like a bigger window too (say 1280×800 or such). Any pointers?


    1. See this article for further detail:

      Seems like use of the edidparser and tvservice programs are necessary (in the “”/opt/vc/bin/” directory) to scan for EDID standard codes, then fix them into the configuration.

      I did also find the original list in Wikipedia as my article suggested when searching on HDMI and EDID. But you can’t beat using values your own Pi has negotiated successfully with the monitor. Should be much more reliable than taking any value from the internet.

      As we are talking about headless mode it should not be an issue; but whilst on the subject of HDMI modes be aware BBB only supports analogue sound over HDMI and not in full HD. So the default 720p mode is the best of both worlds. Should be modes 4 1280×720 @ 60Hz or mode 19 @ 50Hz.

      I found some discussion of extended audio support being coded for BBB towards the end of 2013, which would be fantastic if that were any kind of digital audio. Right now Raspberry Pi has the upper hand over BBB on Full HD AV output.

  6. Excellent and much simpler than instructions I have seen for making tightvnc bootable however, I have a question. Following the code above you are making and executable file ~./xsessionrc which gives the command and parameters to start the vmc session. Then you make this file executable with chmod 775. There is no code anywhere that refers to this file on bouts so how does the pi know to run this at reboot?

    1. That is a standard X-Windows system start-up file, hence the “XSESSION” part of the name for X-Windows and “RC” part of the name which is often used in Linux start-up scripts. I’m aware I need to update this procedure for the latest distributions available for Raspberry Pi and Pi 2. Things have changed now more popular Linux distributions are stable on the Pi. The correct start-up files to edit can vary depending on your chosen OS image, e.g. Ubuntu completely changed its start-up mechanism.

  7. Feeling quite pleased with myself. I am a NOOB and your brilliant instructions worked first time. Thank you.
    Next problem. I want to use my Raspberry Pi with this monitor, an Asus Memo Pad 7, but without an internet connection. Would I have to make the Pi a WiFi Access Point. The Android and Pi would never be more than half a metre apart.

    1. Thanks! Yes it’s pretty straightforward to make the Pi a hotspot, you’ll find plenty of quick start instructions about that already. It’s also possible to set-up a dual configuration where an internet access point will be used when available and when not they’ll just talk between themselves. I’m about to write an article on that because some of the settings can be complex and don’t work in certain combinations.

Leave a Reply

Your email address will not be published. Required fields are marked *