Raspberry Pi Shairport build instructions

This post has been updated with new build instructions.

Below you will find instructions on how to build the Preconfigured Airplay speaker (Shairport) image. You may also find a thread about this build in the Raspberry Pi Forums.

The image assumes you’re starting out with the the standard Raspbian install. If you are starting out with Raspbmc as a base, read this additional information when you get stuck.

This tutorial will be run as root. Log in using the pi user and then do:

Standard configuration

apt-get update && apt-get upgrade

Make sure to run expand_rootfs and reboot, otherwise you will run out of free space!


apt-get install build-essential libssl-dev libcrypt-openssl-rsa-perl libao-dev libio-socket-inet6-perl libwww-perl avahi-utils pkg-config git chkconfig libssl-dev libavahi-client-dev libasound2-dev pcregrep pgrep

In case you are having issues with the prequisites, there is som help here:

Make sure to update the firmware, this will avoid popping noise when starting the speaker

git clone git://github.com/Hexxeh/rpi-update.git

We need to change the ALSA config slightly, otherwise Shairport will output an error – “Unknown PCM cards.pcm.front”

nano /usr/share/alsa/alsa.conf

Change the line “pcm.front cards.pcm.front” to “pcm.front cards.pcm.default”

We need to fix issues with avahi-daemon, which will return the error “avahi-daemon disabled because there is a .local domain” on many networks:

The solution is to modify the avahi-daemon init.d script.

nano /etc/init.d/avahi-daemon

Find the line starting witH DISABLE_TAG and change the filename to an invalid file, like this:


(Note DISABLED at the end)

Restart avahi-daemon and make sure it is run on boot

service avahi-daemon restart
chkconfig avahi-daemon on

Source (original issue)

Now we’re going to test the audio:

wget https://snippets.khromov.se/wp-content/uploads/2013/04/piano2.wav
aplay piano2.wav

You should hear audio through your speakers. Audio file credit

Installing Shairport

git clone -b 1.0-dev git://github.com/abrasive/shairport.git
cd shairport
make install

Start it to see if everything is working:

./shairport -a 'Shairport 1'

Volume levels are a bit low, raise the volume with the following command:


Keep it at about 85. (0 or negative gain). Going close to 100 will distort the audio output.

Autostarting Shairport on boot

We can use the included boot script, but we need to fix some issues with the script related to ALSA permissions and install paths.

Use this script, which changes the running user (for ALSA permissions) and removes some faulty install detection:

Download the modified startup script here. (GitHub gist)

Paste the contents of the script above in a new file:

touch /etc/init.d/shairport

Toggle the script on and off again. (We will see why below)

chkconfig shairport on
chkconfig shairport off


Starting shairport on boot turns out to be very tricky – sometimes shairport starts before avahi-daemon, which makes shairport fail.

To fix this we make a tiny watchdog script that makes sure shairport is always running.

Create a new text file named shairport-watchdog.sh in /root:

touch /root/shairport-watchdog.sh

Paste the following:

# find service pids
pgrep shairport

#if we get no pids, service is not running

if [ $? -ne 0 ]
 service shairport start
 echo "shairport started or restarted."

Edit the file /etc/crontab and add the following line:

* * * * * root /bin/sh /root/shairport-watchdog.sh > /dev/null

The script will now check if shaiport is running every minute, and if not start it. This has the added benefit of restarting shairport if it crashes.

If you know of a cleaner way to declare avahi-daemon dependency in the init.d script for shairport, drop me a comment! There is an ongoing thread on Github about that here. Shairport Issues have been removed from GitHub

Some final cleanup:

chown -R pi:pi /home/pi/

And we’re done!

USB Sound Cards

Check out this tutorial, which has instructions for using Shairport with USB sound cards.

Setting up Wifi

Although it’s not provided in the image, it is possible to set it up with conventional means. Link

51 thoughts on “Raspberry Pi Shairport build instructions

  1. Pingback: Preconfigured Airplay speaker (Shairport) – Downloadable Raspberry Pi image | Useful snippets

  2. James

    Thanks Stanislav, this is great! I had some trouble in places because I was in the wrong directories when running certain commands, but I can get it working over Wi-Fi now up until the last part of making it start up on reboot. I’m doing something wrong I think. It doesn’t run on boot so I need to run the script manually. Then the broadcast name is always ‘Shairport on raspberry pi’ rather than the name in the script. If it’s related I also get the following readout when running ‘chkconfig shairplay on’:

    insserv: warning: script ‘K01shairport’ missing LSB tags and overrides
    insserv: warning: script ‘shairport’ missing LSB tags and overrides
    insserv: script avahi-daemon.save.1: service avahi already provided!
    insserv: script avahi-daemon.save.2: service avahi already provided!

    Best regards

    1. Stanislav Khromov Post author

      Hey James,

      The warnings when running chkconfig are not a problem – the startup script should still work.

      However, remove the files avahi-daemon.save.1 and avahi-daemon.save.2, they are probably some old temporary files you left in the init.d dir, and they are being picked upp by Debian.

      The issue is likely that the Wi-Fi is not yet connected when Shairport starts up. I think you would need to change the startup script and use “Required-start” to make sure Wi-Fi is connected before starting Shairport.

      Here is some info on that:

      I would also suggest you start out from the pre-built image which has everything configured (except Wi-Fi):

      1. James

        Thanks. I tried with the prebuild and everything works perfectly now also over wi-fi. I’ve done this now to both my raspberry pi’s. On first boot it doesn’t work of course because the wi-fi isn’t set up, but after setting up the wi-fi and then rebooting it all works great. Since I have a monitor attached to the HDMI i have to change the audio output to force it to go to the jack that’s attached to my speakers. I just use ‘sudo amixer cset numid=3 1’ to achieve this. Many thanks!

  3. Jona


    First of all, nice share. Although i cannot get it to work. I’ve configured WIFI and audio is working. Also the airport client starts, but it mostly doesn’t show op under the device list in iTunes. and when it does show up i cannot connect to it.

    I’ve restarted the avahi daemon and also shairport, but no luck.

    1. Stanislav Khromov Post author

      Can you try with a wired connection?

      avahi-daemon has to be running, otherwise you won’t find the Shairport.

      Also, try starting it with:

      ./shairport -a ‘Shairport 1’

      That way you should see any errors in your RPi console when you connect to Shairport. Check the Shairport bug tracker on Github, there are some bugs reported already.

      Lastly, you can try the pre-built image:

    2. Kiran B

      Actually I found that I had to force the audio through the analog port as opposed to the hdmi using this:

      sudo amixer cset numid=3

      where n is 0=auto, 1=headphones port, 2=hdmi

      1. Kiran B

        I apologize, the code didn’t come out right, here is what it’s supposed to be:

        sudo amixer cset numid=3 n

        where n is 0=auto, 1=headphones, 2=hdmi

  4. Tim Walker

    I had to build from scratch using your instructions since the pre-configured file wouldn’t fit onto my 4GB card. But working great over a wired connection, which is how I plan to use it for now. Thanks!

  5. Pingback: Installer Airplay sur votre Rasperry | Aube-tech, le blog

  6. Jeff

    Holy mackerel, this is great! Thank you very much Stanislaus. My first day with my new RPi and it’s been a good one. I followed your instructions to the letter and it all worked perfectly the first time.

  7. Johan

    Great tutorial. I needed to add ‘sudo alsactl store 0’ for the alsa volume to be kept at 85% after rebooting.

  8. Adam

    Thank you, this guide is fabulous! Works as a charm.

    (I had some small problems but that was because I skipped the “apt-get update” command.. :)

  9. Pingback: Project CarFire: RasPi-based In-Car Music Streaming Box | BrainDeadLock Labs

  10. Pingback: Raspberry Pi: Doing useful things « Bethany Corcoran

  11. Dean M.

    When installing on Raspbmc, I got the following five errors:

    1. raspi-config is not supported on Raspbmc, but filesystem is already expanded so we are OK.

    2. When installing dependencies:
    Package pgrep is not available, but is referred to by another package.

    pgrep was already installed, no problem here.

    3. When running make:
    root@raspbmc:/home/pi/shairport# make
    cc -D_REENTRANT -I/usr/include/alsa -D_REENTRANT shairport.c daemon.c rtsp.c mdns.c common.c rtp.c player.c alac.c audio.c audio_dummy.c audio_pipe.c audio_ao.c audio_pulse.c audio_alsa.c avahi.c -lm -lpthread -lssl -lcrypto -lao -lpulse-simple -lpulse -lasound -lavahi-common -lavahi-client -o shairport
    audio_pulse.c:31:26: fatal error: pulse/simple.h: No such file or directory
    compilation terminated.
    make: *** [shairport] Error 1

    To fix, I did
    sudo apt-get install libpulse-dev

    and then make worked.

    4. When I tired to run, I got:
    pi@raspbmc:~/shairport$ sudo shairport -a ‘AirPi’
    Listening for connections.
    ALSA lib confmisc.c:768:(parse_card) cannot find card ‘0’
    ALSA lib conf.c:4241:(_snd_config_evaluate) function snd_func_card_driver returned error: No such file or directory
    ALSA lib confmisc.c:392:(snd_func_concat) error evaluating strings
    ALSA lib conf.c:4241:(_snd_config_evaluate) function snd_func_concat returned error: No such file or directory
    ALSA lib confmisc.c:1251:(snd_func_refer) error evaluating name
    ALSA lib conf.c:4241:(_snd_config_evaluate) function snd_func_refer returned error: No such file or directory
    ALSA lib conf.c:4720:(snd_config_expand) Evaluate error: No such file or directory
    ALSA lib pcm.c:2217:(snd_pcm_open_noupdate) Unknown PCM default
    FATAL: Alsa initialization failed: unable to open pcm device: No such file or directory

    Shutting down…

    I fixed this by : sudo modprobe snd_bcm2835
    And then it ran. To make sure this module always loaded, I added the line
    to /etc/modules

    5. The init.d script refers to shairport being installed in /usr/bin/shairport – Raspbmc installed it to /usr/local/bin/shairport
    6. Cron is not enabled by default on Raspbmc – turn it on using the Raspbmc config under Programs in the UI

    I couldn’t get the watchdog running, but that’s probably something I’m doing.

    1. Stanislav Khromov Post author

      Thanks for the additional instructions, I added a link to them in the main post and clarified that these instructions are for Raspbian.

      It looks like you got everything working, which is great.

      Which error are you getting from the watchdog script? If you run it from command line it should just output some process id’s, like:

      If you get similar output, it means the script is working, just stick it in your crontab and you’re all set.

  12. Caeden

    Hello, when i do ./shairport -a ‘Shairport 1′ It just says Listening for connections, and nothing else happens and it wont let me connect to it on my iPhone.

    1. Stanislav Khromov Post author

      If you let it wait for a while (2-3 minutes), does any error message occur in the console?

        1. Stanislav Khromov Post author

          Hi Caeden,

          What image did you start from? Raspbian?

          Can you check if you have any firewall that may be blocking the connection between your Pi and your phone?

          You can check if iptables is blocking stuff locally no the Pi by issuing:
          sudo iptables -L
          (There should be no rules)

          Other than that, can you try out the pre-built image? If you are still having issues with that build a network problem (firewall or other reason) is highly likely.

          Here is a link to the pre-built image:

          1. Caeden

            Yes i started from Raspian, i dont think its anything to do with firewall because i had it installed before. Ill try the pre-built image.

      1. Caeden

        I am now getting this
        pi@raspberrypi ~/shairport $ ./shairport -a ‘AirPi’
        FATAL: could not bind any listen sockets!
        Shutting down…

        when i try and enable it.

  13. jack

    FATAL: could not bind any listen sockets!could not bind any listen sockets!
    Caeden, exactly the same problem, which results with the raspify connected with an external usb/dac

  14. Darren

    Could I recommend adding the line “ipv6” to the end of /etc/modules
    It is required for Itunes 11.1 and newer.

  15. Texy

    thanks for the instructions. I didn’t go with the pre-built image as I wanted to use a specific build that supported my 2.8″ TFT shield board. I first got the shairport side of things working and then setup my pi to be a stand-alone wireless network source so that it could be used wherever. The next thing that would be very useful would be able to get the ID3 tag information so that it could be shown on my display. I don’t think shairport support this currently, which is a shame.

      1. Keith

        shairport works for me with iOS 7. Realize that in iOS 7 you have to drag the bottom of the screen (in the Music app) up to reveal the AirPlay menu as well as other options. Otherwise, it’s hidden.

  16. Pingback: Építsünk bárhol használható AirPlay servert magunknak, mert az jó | eFi.blog

  17. Rob Hall


    Might sound a bit of a daft question but how are you supposed to switch down with no keyboard/ monitor? Is it just a plug pulling exercise as I always believed this was BAD?

  18. Pingback: Frozen Industries » Raspberry Pi as a Car AirPlay Receiver

  19. Alessandro Ferri

    Hi Khromov,
    I have a problem with shaiorport that I can not solve. First of all, the problem occurs if I install both shairport in the last image of that Raspbian or in your preconfigured image. I come to the point. Along with shairport, I also have to install pulseaudio, after installing pulseaudio, I configure pulseaudio and I recompile shairport, an than reboot. Everything seems to work correctly for a while, but if I try to disconnect and reconnect to shairport “AirPI” with iTunes or my iPhone, the first time I do not hear the sound an the second time I try to reconnect to shairport, I come back to iTune error:

    There was an error while connecting to the AirPlay device “AirPi.” There was an unknown error (-15000).

    1. Stanislav Khromov Post author

      Hey Alessandro, did you get this solved?

      If you flash the preconfigured image to SD and run it without any modifications, does it work properly?
      If yes, then something about Pulseaudio may be causing the issues. Check the Shairport error log.

  20. Joe

    I must have spent at least half an hour on this, but I can’t seem to add a space into the AP_NAME string.
    I’ve tried many different methods of escaping it but with no success.

    Think you could help a guy out? :)


    1. Stanislav Khromov Post author

      Hey Joe,

      Which part are you configuring? Shairport or Wifi for your raspi?

  21. Julian

    Just wanted to say thanks for this, and to add a suggestion. The first time I built this it worked great for a bit, but lost network connection after leaving it on for a while for whatever reason; maybe there’s something weird with my network idk. Unplugging it and plugging it back in is the easiest quick fix — a lot better than finding a serial cable and diagnosing it when I just want to play music. But of course this corrupts the SD card after a week or so. I had to start over twice because I kept corrupting the card.

    I finally made the OS read-only. Now I can unplug it all I want and nothing bad happens, it’s been stable for a couple months. I’d recommend making this part of the build steps and the pre-built image.

    1. Stanislav Khromov Post author

      Hey Julian,

      Can you provide steps for making the OS read-only? If you do I can incorporate it into the build instructions. Thanks!

      As for your problem, do you run the Pi on Wifi?
      If you do, try a cable and see if it’s a real crash or if Shairport just bailed. The watchdog should restart shairport but maybe there’s some weird edge case not accounted for.

  22. Garrett

    Hi, I’ve been attempting to password protect my shairport network by editing the shairport file in init.d, and it doesn’t seem to be working. If you were to add a password to your network, how would you do it?

  23. erik

    may sound like a daft question but how to i change the name from shairport to for example front room i am currently using the automatic start script any ideas ?

  24. Pingback: Raspberry PI als AirPlay Client mit shairport | pi.jukeman.de

  25. Pingback: Airplay with Shairport on Raspberry Pi | The Crane Has Landed

  26. Rasp Joe


    Thank you so much for this tutorial, it helpped me a lot to get my Rasp started with Shairport. I final question though: I have multiple sources which should be able to stream to my Rasp. Can Shairport be run multiple times with different ports and mix the sounds together?

    1. Stanislav Khromov Post author

      Hey Joe,

      Not on Shairport I think… The original maintainer no longer develops it. However, there are currently 374 forks available, I found this one which has received a lot of updates like synced audio between multiple Raspberry Pi:s, check it out, maybe it has the feature you are looking for:

  27. Pingback: How Can I Uninstall Shairport? | DL-UAT

  28. Pingback: Raspberry PI als AirPlay Client mit shairport | pi.jukeman.de

Leave a Reply

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

Markdown is allowed in comments.