Headless Raspberry Pi 4 Remote Desktop VNC Setup (Mac + Windows, 13 Steps)

mitch

This article covers how to setup a Raspberry Pi 4 Model B with a desktop for headless remote access over SSH, WiFi and VNC from scratch. You won't need an extra mouse, monitor or keyboard.

Step 1. Download Raspberry Pi OS Buster with desktop

These instructions are for a Raspberry Pi OS Buster (formerly Raspbian Buster) image that I downloaded from here:

https://www.raspberrypi.org/software/operating-systems/

I'm using the with desktop and recommended software image:

  • Release date: May 7th, 2021
  • Kernel version: 5.10

Step 2. Burn the Raspberry Pi image to the SD card

balenaEtcher

To burn an image to the SD card you can use Etcher.

To run Etcher is pretty straight forward.

Put a blank mini SD card and adapter into your machine. No need to format it. You can use a new SD card right out of the package.

  1. Select image - browse to the zip file you downloaded
  2. Select drive - it may find the SDHC Card automatically
  3. Click Flash!

After you flash (burn) the image, Finder (Mac) or File Explorer (Windows) may have trouble seeing it. A simple fix is to pull the SD card out then plug it back in. On a Mac it should appear on the desktop with the name boot. On Windows it should appear in File Explorer with the name boot followed by a drive letter.

Step 3. Enable ssh to allow remote login

For security reasons, ssh is no longer enabled by default. To enable it you need to place an empty file named ssh (no extension) in the root of the boot disk.

Mac instructions (enable ssh)

Open up a terminal window and run this command:

touch /Volumes/boot/ssh
Windows instructions (ssh)
  • Run Notepad
  • In a new file put in one space and nothing more
  • Click File / Save As ...
  • Be sure to set Save as type to All Files (so the file is NOT saved with a .txt extension)
  • Call the file ssh and save it
  • Close the file

If you are comfortable with the Windows command line you could try this instead (untested!):

  1. Open up a command line
  2. Switch to the drive and root where boot is located:
  3. Type: type NUL >> ssh
  4. Verify that file ssh was created

Step 4. Add your WiFi network info

Create a file in the root of boot called: wpa_supplicant.conf (instructions below). Then paste the following into it (adjusting for your ISO 3166 alpha-2 country code, network name and network password):

country=US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
    ssid="NETWORK-NAME"
    psk="NETWORK-PASSWORD"
}
Mac instructions (wifi settings)

Create a new empty file that will hold network info:

touch /Volumes/boot/wpa_supplicant.conf

Edit the file that you just created and paste the text above into it (adjusting for the name of your country code, network name and network password):

Windows instructions (wifi settings)
  1. Run Notepad
  2. Paste in the contents above (adjusting for the name of your country code, network name and network password)
  3. Click File / Save As ...
  4. Be sure to set Save as type to All Files (so the file is NOT saved with a .txt extension)
  5. Call the file wpa_supplicant.conf and save it
  6. Close the file

Step 5. Eject the micro SD card

  • Right-click on boot (on your desktop or File Explorer) and select the Eject option
  • This is a "logical" eject - meaning it closes files and preps the SD card for removal - you still have to pull the card out yourself

Step 6. Boot the Raspberry Pi from the micro SD card

  • Remove the mini-SD card from the adapter and plug it into the Raspberry Pi
  • Raspberry Pi 4: Plug a USB-C power supply cable into the power port
  • Give the Pi plenty of time to boot up (it can take as much as 90 seconds -- or more)

Step 7. Login remotely over WiFi

This part assumes that ssh is enabled for your image and that the default user is pi with a password of raspberry.

NOTE: Your machine must be on the same WiFi network that you configured the Pi for.

Mac instructions (login over wifi)
  • Open up a terminal window
  • Run the following commands:
ssh-keygen -R raspberrypi.local
ssh pi@raspberrypi.local
  • Don't worry if you get a host not found error for the first command - the idea is to clear out any previous references to raspberrypi.local
  • If the pi won't respond, press Ctrl-C and try the last command again
  • If prompted with a warning just hit enter to accept the default (Yes)
  • Type in the password -- by default this is raspberry
Windows instructions (login over wifi)

Install Bonjour

You can find Raspberry Pi's on your network using their hostname followed by .local (example: raspberrypi.local). But to do that in Windows you have to install the Bonjour service first.

If you have iTunes installed on Windows you probably don't have to do this. But if you don't, browse to:

Download Bonjour Print Services for Windows v2.0.2
and run the installer.

Install Putty

If you already have Putty installed, skip to the next section.

  • Browse to:
    https://www.putty.org
  • Download the 64-bit MSI (Windows Installer)
  • Open it to run the installer (if asked for permission, click Yes)
  • Select: Add shortcut to PuTTY on the Desktop

Login over WiFi using Putty

This part assumes that ssh is enabled for your image and that the default user is pi with a password of raspberry.

  1. Launch Putty
  2. Set the Host Name (or IP address) field to raspberrypi.local
  3. By default the Port should be set to 22 and Connection type should be set to SSH
  4. Click Open
  5. If you see a Security Alert select Yes
  6. A new terminal window should appear prompting you for a user name
  7. The default user name is: pi
  8. The default password is: raspberry

Step 8. Change your hostname and password

Congratulations! You can now access your Raspberry Pi over wifi!

If you can't connect, see the troubleshooting section near the end of this article. You may need to make some adjustments for your network.

Because your pi is now on the network, you should immediately change the hostname and password.

At the Pi command line type:

sudo raspi-config

Select the options for changing the hostname and password. On a new image, I would also recommend expanding the file system (now under the Advanced options). Once the changes are made, reboot.

Remember that once you reboot, you will need to use the new hostname to login over ssh. For example, if your new hostname is mypi you would connect like this on a Mac:

ssh pi@mypi.local

On Windows you would need to change the host name in Putty to mypi.local.

Step 9. Get the latest updates

Once connected over WiFi, the next thing you should do is run some updates:

sudo apt-get update -y
sudo apt-get upgrade -y
sudo apt dist-upgrade -y

Step 10. Enable VNC

By default a Raspberry Pi does not allow a remote VNC connection. You have to enable it through raspi-config. It will also install the required VNC server.

sudo raspi-config
  • Select Interfacing Options
  • Select VNC
  • For the prompt to enable VNC, select Yes (Y)
  • For the confirmation, select Ok

Step 11. Important! Change the default screen resolution

There is a weird quirk where you must change the screen resolution or VNC will report "Cannot currently show the desktop."

Still from within raspi-config:

  • Select Display
    • on older versions this was under Advanced Options
  • Select Resolution
  • Select anything but the default (example: 1024x768)
  • Select Ok

Once you've established that it works, you can go back and try other screen resolutions.

  • Select Finish
  • For the reboot prompt, select Yes

Step 12. Install the RealVNC viewer on your computer, smartphone or tablet

Download the RealVNC viewer for your operating system.

Browse to:

For some operating systems the downloaded file may be an installer that needs to run. If that's the case, run the installer.

Step 13. Connect over VNC

Launch the VNC viewer on your computer and type the name of the Raspberry Pi server into the Connect address bar.

For example: mypi.local

If prompted, enter your Raspberry Pi username and password to connect.

Congratulations! You should now be connected over VNC to your Raspberry Pi desktop!

Troubleshooting

Remote desktop grabs the mouse

  • Wave your mouse over the top middle of the screen
  • A special VNC only menu should appear
  • Wave your mouse over the first menu option
  • Select Exit full screen if that is the current option
  • Put your mouse over the lower right corner
  • Drag the corner to make the remote screen smaller
  • The remote desktop may still have focus
  • Click your mouse somewhere on your host desktop to regain control

Smartphone clicks not working

When using the VNC viewer on a smartphone you have to position the mouse cursor. Then tap to click.

Conclusion

In this article you learned how to do the following:

  • perform a headless install of the Raspberry Pi OS desktop
  • enable and install a VNC server on a Raspberry Pi
  • install a VNC viewer on your computer, smartphone or tablet
  • connect to a remote desktop over VNC

Related Articles

Here is a list of my related articles that you may find interesting:


References

  • Introducing PIXEL (raspberrypi.org) [1]