To make this work, macOS requires each service to be running and advertised to the local network via Bonjour. On the Raspberry Pi this means we need to configure the default VNC server RealVNC, install Samba for file sharing, and advertise both services across the local network with Avahi, the Bonjour implementation on Linux. Onwards!

System Setup

This guide assumes your Raspberry Pi is already setup and connected to your local network. All command line instructions can either be executed directly on the Raspberry Pi, or remotely via SSH which you can achieve by simply following the official SSH guide.

I’m using a Raspberry Pi 4, Model B, running RaspberryPi OS (Debian Bullseye) with desktop, and macOS Monterey. The Raspberry model shouldn’t matter for the scope of this guide, and the instructions should also work some macOS versions down.

Furthermore, this guide should also work on any Linux distribution like Ubuntu or Debian itself. The principals to make a Raspberry Pi show up in macOS are applicable to any Linux distribution capable of running a VNC server, Samba, and Avahi.

Screen Sharing with VNC

Screen sharing using the default VNC server included in Raspbian called RealVNC is sufficient to make it work with the default macOS Screen Sharing app. Only the user authentication mechanism has to be changed in RealVNC.

Depending on your Raspbian image the RealVNC server is already installed and configured. For getting it installed, you can follow the official guide where you end up activating the VNC server either:

• graphically in Raspberry Pi Configuration > Interfaces
• on command line via sudo raspi-config > Interfacing Options

You can check the status of the VNC server with:

sudo service vncserver-x11-serviced status

Which should give you something like this:

The important part is Found running X server cause that’s the graphical interface we are going to connect to. This will only be present if your Raspberry Pi is set to boot up into a desktop GUI which can be configured under sudo raspi-config > Boot Options > Desktop / CLI. If you use your Raspberry Pi with a display attached, this should be the default.

To be able to connect from macOS without additional software, you have to change the authentication mode. By default, RealVNC uses the system accounts to authenticate but for whatever reason this is not supported by macOS. But VNC password authentication is, so let’s switch to that.

If you have GUI access to your Raspberry Pi you will find the RealVNC icon at the top right in your menubar, and in the app’s options under Security you can switch the Authentication to VNC Password. This will prompt you to enter and confirm a new password which we are going to use to connect from macOS.

Hit Apply & OK and reboot your Raspberry Pi.

This can also be done via SSH by first switching to VNC password auth:

sudo nano /root/.vnc/config.d/vncserver-x11

# in there add the line:
Authentication=VncAuth

Then set the VNC password with:

sudo vncpasswd -service

Now restart VNC server or simply reboot your Raspberry Pi.

To test the connection, you should make note of your local network IP address. To do so on your Raspberry Pi:

ifconfig

# will give you e.g. `inet 192.168.178.27`

Now we can verify the connection from macOS by selecting from the menubar in Finder Go > Connect to Server… and use the above IP as the host:

You should be prompted for the VNC password setup in RealVNC in the step above and afterwards should see your Raspberry Pi desktop from macOS:

Now, keeping track of IP addresses is not fun at all so we still need to make the Screen sharing button appear in Finder with Avahi. But first, file sharing.

File Sharing with Samba

By now, macOS uses Samba as its default network sharing protocol. So you can install it on the Raspberry Pi and macOS will handle it:

sudo apt update && sudo apt upgrade
sudo apt install samba samba-common-bin

By default, Samba allows access to the home folder of the logged in user so no further shares need to be configured if you just want access to your home folder. Again, macOS does not like using standard UNIX accounts for authenticating with Samba, so we need to set a dedicated Samba password.

To do so:

sudo smbpasswd -a pi

Where pi refers to the user account on the Raspberry Pi you want to connect to.

By default, Samba exposes home folders as read-only. To change that, modify Samba’s main config file smb.conf:

sudo nano /etc/samba/smb.conf

In there, scroll down to the [homes] section and set read only = no to make shared home folders writable.

To share more resources like an external drive, add another section at the end of your smb.conf and make it fully writable:

[sharename]
    path = /mnt/myexternaldrive/
    read only = no
    public = yes
    writable = yes

After setting a new password and modifying smb.conf, restart the Samba service:

sudo service smbd restart

After finishing these steps, your Raspberry Pi should already show up in Finder, ready for file sharing. Clicking on Connect in Finder will prompt for the just created Samba password and upon entering it you should see your home folder listed and browsable in Finder.

We still want that Share Screen button though, and the Finder representation looks a bit shitty. Bonjour and Avahi to the rescue.

Bonjour Server Discovery and Icon with Avahi

As you probably have noticed, Samba is advertised by default via Bonjour without defining an Avahi service for it. But it advertises the hostname in screaming ALL CAPS sometimes, and the device icon is just a question mark. We can change all that by defining dedicated service files for everything we want to advertise in the local network.

For VNC we need to create and define a dedicated rfb.service:

sudo nano /etc/avahi/services/rfb.service

And fill it with an Avahi service description for VNC:

<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
  <name replace-wildcards="yes">%h</name>
  <service>
    <type>_rfb._tcp</type>
    <port>5900</port>
  </service>
</service-group>

The %h in the <name replace-wildcards="yes">%h</name> line will simply be substituted by the global hostname setup in your Raspberry Pi config. Make sure to use always the same name line in each service, so macOS will attach all the advertised services to one server. Alternatively, you could also setup different servers to show up in Finder sidebar for different services, e.g. VNC on %h and SMB on %h.

And with all that you should end up in macOS Finder with the buttons we wanted for file and screen sharing:

But nobody can live with that default question mark as the device icon and the name still sometimes switches between the actual hostname, and a nasty SHOUTING DEVICE NAME in all caps.

To optimize all that, we have to add a dedicated Samba service, despite it already being advertised by default. But macOS uses most information from this service to represent the server in Finder so we can use it to customize that.

Create and open the new smb.service:

sudo nano /etc/avahi/services/smb.service

And fill it with:

<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
  <name replace-wildcards="yes">%h</name>
  <service>
    <type>_smb._tcp</type>
    <port>445</port>
  </service>
  <service>
    <type>_device-info._tcp</type>
    <port>0</port>
    <txt-record>model=Xserve</txt-record>
  </service>
</service-group>

You see that model=Xserve service part? That will make your Raspberry Pi show up with a Xserve icon in Finder for some nostalgia feeling.

You can use any Mac, iPhone, iPad, or other Apple device model string, like model=MacPro7,1 or model=iPad6,12.

Using the model string essentially works for any device which has an icon in macOS, which you can check out in Finder with, referring to the com.apple.* named icons:

open /System/Library/CoreServices/CoreTypes.bundle/Contents/Resources/

Now restart the avahi-daemon to pick up the changes:

sudo service avahi-daemon restart

And with all that you should end up in macOS Finder with the buttons we wanted for file and screen sharing, along with a nice hostname and icon for it:

On the macOS side, sometimes Finder does not pick up changes in Bonjour/Avahi services right away. In that case, a killall Finder helps to force them.

As a bonus you should also add services for SFTP & SSH so your server will show up in dedicated apps on macOS and iOS making use of Bonjour to discover and list servers they can connect to. Any macOS device does this in a local network too.

For SFTP:

sudo nano /etc/avahi/services/sftp.service

<?xml version="1.0" standalone='no'?>
 <!DOCTYPE service-group SYSTEM "avahi-service.dtd">
 <service-group>
   <name replace-wildcards="yes">%h</name>
   <service>
     <type>_sftp-ssh._tcp</type>
     <port>22</port>
   </service>
</service-group>

For SSH:

sudo nano /etc/avahi/services/ssh.service

<?xml version="1.0" standalone='no'?>
 <!DOCTYPE service-group SYSTEM "avahi-service.dtd">
 <service-group>
   <name replace-wildcards="yes">%h</name>
   <service>
     <type>_ssh._tcp</type>
     <port>22</port>
   </service>
</service-group>

Make sure to use the port you use for SSH access on your server if you are not using the default one. All changes to Avahi services require a restart of the daemon:

sudo service avahi-daemon restart

But to be absolutely sure, you should reboot your Raspberry Pi with:

sudo reboot

You can verify all the services advertised via Bonjour/Avahi with this handy macOS app called Discovery:

Connect from iOS & iPadOS

With the Raspberry Pi setup for macOS connection, you can now connect to your Raspberry Pi’s file system from within the iOS Files app too.

Since Raspbian is configured to advertise the raspberrypi.local hostname by default, you can use that name from any device to connect to it without figuring out IP addresses. So from Files, hit the three dots in the upper right corner and tap Connect to Server, and use raspberrypi.local or whatever hostname you use. Enter your user account credentials and you should see your home folder in the Files app.

As for screen sharing, you can use any VNC app on iPhone or iPad and it should work the same way as on macOS with using the VNC password. For me, Edovia’s Screens app works pretty well.

There is also a way to make the Raspberry Pi available via AirDrop. The Open Wireless Link (OWL) project set out to reverse engineer the protocol used for AirDrop, Apple Wireless Direct Link (AWDL). The setup is rather hacky and unstable but they provide a tutorial for the Raspberry Pi 3 if you want to try.