Install dlib on the Raspberry Pi

A few weeks ago I did a blog post on how to install the dlib library on Ubuntu and macOS.

Since Raspbian, the operating system that (most) Raspberry Pi users run is Debian-based (as is Ubuntu), the same install instructions can be used for Raspbian as Ubuntu…

…however, there’s a catch.

The Raspberry Pi 3 ships with only 1GB of RAM. This 1GB of RAM is responsible for all system operations, displaying the GUI/desktop, and handling our compile.

In fact, if you tried to compile dlib on the Raspberry Pi, your compile likely bombed out with an error.

In order to get dlib with Python bindings to successfully install on your Raspberry Pi, you need to update your system to reclaim as much memory as possible as well as update your swap file size.

Luckily, this isn’t as challenging as it sounds, and if you follow the steps detailed in this guide, you’ll have dlib installed on your Raspbian system in the next 45 minutes.

To learn how to install dlib on your Raspberry Pi, just keep reading.

Install dlib on the Raspberry Pi

The first part of this tutorial discusses the common memory error you’ll encounter when trying to compile dlib with Python bindings on your Raspberry Pi.

We then move into my six step guide to installing dlib on the Raspberry Pi.

Finally, we’ll wrap up with an example demonstrating how to detect facial landmarks using dlib, Python, and the Raspberry Pi.

Running into memory errors? System crashing?

If you used the Ubuntu instructions from my previous dlib install tutorial to install dlib on your Raspberry Pi, your compile likely bombed out with an error message similar to this one:

Figure 1: The dlib compile failing on the Raspberry Pi due to the C++ compiler being killed.

The reason for this error can be found in the highlighted box:

c++: internal compiler error: Killed (program cc1plus)

This error message boils down to the dlib compile program using too much memory and the Raspbian operating system killing the process, preventing the Raspberry Pi from seizing.

However, the preventative measures weren’t enough — 3 out of the 5 times I tried to compile dlib on my Raspberry Pi without updating my swap file size, boot options, and memory split (detailed below), my Pi simply locked up and I had to hard reset it.

In order to get dlib with Python bindings installed on Raspbian, we need to reclaim as much available memory as possible. We’ll dive into how to do this in the next section.

Step #1: Update swap file size, boot options, and memory split

Preparing your Raspberry Pi for the dlib compile is divided into three steps, each of them with the same goal — to increase the amount of memory available for the compile:

  1. Increase your swap file size.
  2. Switch your boot options.
  3. Update your GPU/RAM split.

Note: For nearly all screenshots in this tutorial, I was SSH’d into my Raspberry Pi from my host macOS system (that is why the screenshots are from the macOS terminal rather than the Raspbian terminal).

Increase swap file size

Swap files, or swap space, is space on a hard disk/memory card used as virtual memory as an extension to a system’s real memory (RAM).

Enabling swap files allows your operating system to “pretend” like it has more on-board memory than it actually does. Using the swap file architecture, pages in RAM are “swapped out” to disk until they are needed again in which case they are “swapped in”.

Nearly all major operating systems support swapping to some degree.

In Raspbian, the dphys-swapfile solution is used with a default of 100MB dedicated to swap on our card.

In order to update the size of our swap, we need to edit the dphys-swapfile configuration file, which is located in /etc/dphys-swapfile . You can edit the configuration using your favorite text editor:

Scroll down to the configuration which reads:

CONF_SWAPSIZE=100

And then update it to use 1024MB rather than 100MB:

Figure 2: Updating the Raspbian swap size to be 1024MB rather than 100MB.

Notice here how CONF_SWAPSIZE=1024  — this will be more than enough swap for us to compile dlib on our Raspberry Pi.

Note: Increasing swap size is a great way to burn out your Raspberry Pi card. Flash-based storage have limited number of writes you can perform until the card is essentially unable to hold the 1’s and 0’s anymore. We’ll only be enabling large swap for a short period of time, so it’s not a big deal. Regardless, be sure to backup your .img  file after installing dlib just in case your card dies unexpectedly early. You can read more about large swap sizes corrupting memory cards on this page.

After you have updated the /etc/dphys-swapfile  file, run the following two commands to restart the swap service:

The start  command will likely take a few minutes to finish executing since the swap size is being increased and re-allocated.

You can then run:

To confirm that your swap size has been increased.

Here you can see that my swap is 1024MB, up from the previous 100MB:

Figure 3: Running free -m confirms that the new swap size of 1024MB is being used.

Change your boot options

By default, your Raspberry Pi will boot into the the PIXEL desktop (assuming you’re using the latest version of Raspbian). This is fine; except that the PIXEL desktop requires memory — RAM that we desperately need for the dlib compile.

Instead of booting into the PIXEL GUI, we should instead boot directly to the terminal. This will save us a substantial amount of memory.

To accomplish this, execute:

And then select Boot Options => Desktop / CLI => Console Autologin :

Figure 4: How to set your Raspberry Pi to boot to a terminal rather than a desktop.

This will ensure that your Raspberry Pi boots directly to a terminal, skipping the PIXEL desktop.

However, before you exit raspi-config , be sure to update your memory split, as detailed below.

Update your memory split

By default, the Raspberry Pi allocates 64MB of memory to the onboard GPU. We should reduce this number to 16MB to reclaim memory for the compile.

This is simple enough using raspi-config . Go back to the main screen and select Advanced Options => Memory Split , where you’ll see the 64MB prompt:

Figure 5: Update your GPU/RAM split to be 16MB rather than 64MB.

Update this value to be 16MB and then exit.

Restart your Raspberry Pi

Upon exiting,  raspi-config  will ask if you would like to reboot your system.

Go ahead and reboot, then we can move on with the rest of the install tutorial.

Step #2: Install dlib prerequisites

The dlib library requires four prerequisites:

  1. Boost
  2. Boost.Python
  3. CMake
  4. X11

These can all be installed via the following commands:

The pip  command should already be installed on your Raspberry Pi (you can verify this by executing the pip  command and ensuring that it does indeed exist) — otherwise, you can install pip  via:

Once you’ve verified that pip  is installed, we can move on.

Step #3: Access your Python virtual environment (if you are using them)

All of my OpenCV install tutorials on the PyImageSearch blog make use of Python virtual environments.

Using Python’s virtualenv and virtualenvwrapper libraries, we can create separate Python environments for each project we are working on — this is considered a best practice when developing software in the Python programming language.

I’ve discussed Python virtual environments many times before on the PyImageSearch blog, so I’ll spare any discussion of them here. If you would like to read more about Python virtual environments please refer to any of my installing OpenCV tutorials along with this excellent Python virtual environment primer.

If you would like to install dlib into a pre-existing Python, virtual environment, use the workon  command:

For example, most tutorials here on PyImageSearch create a virtual environment named cv . We can access the cv  virtual environment via:

Otherwise, I suggesting creating an entirely separate virtual environment using the mkvirtualenv  command.

The command below will create a Python virtual environment named py2_dlib  with the Python 2.7 interpreter:

While this command will create a Python 3 virtual environment named py3_dlib :

Please keep in mind that this step is optional, but highly recommended.

For readers who have followed any of my previous OpenCV install tutorials on PyImageSearch, please make sure you access your Python virtual environment before proceeding to Step #4.

Step #4: Use pip to install dlib with Python bindings

We’ll start with the basic NumPy + SciPy stack, followed by scikit-image, a library commonly used in conjunction with dlib:

We can then install dlib via pip  as well:

On my Raspberry Pi 3, this compile took approximately 40 minutes, but as you can see, the library was compiled successfully with no errors:

Figure 6: Successfully compiling dlib with Python bindings on your Raspberry Pi.

Step #5: Test out your dlib install

To test out your dlib install, open up a Python shell (making sure to access your Python virtual environment if you used one), and then try to import dlib :

If you would like to access your OpenCV bindings along with your dlib bindings from the same virtual environment, make sure your cv2.so  bindings are properly sym-linked into the site-packages  directory of your Python virtual environment.

Step #6: Reset your swap file size, boot options, and memory split

Important — before you walk away from your machine, be sure to reset your swap file size to 100MB (using the process detailed in the “Step #1: Increase swap file size” section above).

You can then reset your GPU/RAM split to 64MB as well as update the boot options to boot into the desktop interface versus the command line.

After making these changes, reboot your Raspberry Pi to ensure they take affect.

BONUS: Facial landmark detection with dlib and the Raspberry Pi

As a final example of using dlib on the Raspberry Pi, here is a short example I coded up where we are going to detect facial landmarks in an input image:

For a detailed review of the code above used for facial landmark prediction, please refer to my previous post on the basics of facial landmarks.

To execute the script:

  • Make sure you’ve installed/upgraded the imutils library via pip install --upgrade imutils .
  • Use the “Downloads” section below to download the code + example image + pre-trained dlib facial landmark predictor).

From there, you can issue the following command:

You should then see the following output with the facial landmarks correctly displayed on the input image:

Figure 7: Detecting facial landmarks on an image using dlib on the Raspberry Pi.

Fun Fact: The picture above is of me during my undergraduate college days — I actually had hair back then!

Unfortunately, from my tests, the Raspberry Pi 3 is not fast enough to perform facial landmark detection in real-time. In my experiments there was a significant lag between polling the next frame from the video stream, followed by applying facial landmark prediction, even when using a threaded video stream for optimal performance. The reason for this is because the face detection process is extremely slow.

Keep in mind that the Raspberry Pi 3 processor runs at only 1.2Ghz while the processor on my Mac (and likely your machine) runs at 3.1GHz (or similar). This is a huge increase in speed.

Methods to speeding up dlib’s facial landmark predictor can be found here — I will be reviewing them in a future blog post with accompanying Python implementations to help us obtain real-time facial landmark prediction performance on the Raspberry Pi.

Summary

In today’s blog post we learned how to compile and install dlib with Python bindings on the Raspberry Pi.

In order to install dlib without error on the Raspberry Pi, we had to take a number of precautions related to memory usage, including:

  1. Increasing the amount of swap available to our system.
  2. Booting our Raspberry Pi to the terminal rather than the desktop.
  3. Reducing memory allocated to the GPU and giving it to main memory instead.

By performing these three steps we were able to reclaim enough memory to install dlib on our Raspberry Pi. However, now we’ve run into the issue that the Pi isn’t quite fast enough for real-time facial landmark prediction. We’ll address how to speedup facial landmark prediction in a future tutorial.

Finally, I wanted to mention that next week’s tutorial is on drowsiness detection while driving a motor vehicle, a heavily requested blog post here on PyImageSearch:

Figure 8: A preview of next week’s tutorial on drowsiness detection while driving a motor vehicle.

I’m super excited to be demonstrating how to build a drowsiness detector from scratch, so to ensure you are notified when this can’t miss blog post goes live, be sure to enter your email address in the form below!

Downloads:

If you would like to download the code and images used in this post, please enter your email address in the form below. Not only will you get a .zip of the code, I’ll also send you a FREE 11-page Resource Guide on Computer Vision and Image Search Engines, including exclusive techniques that I don’t post on this blog! Sound good? If so, enter your email address and I’ll send you the code immediately!

, , , ,

31 Responses to Install dlib on the Raspberry Pi

  1. Lorenzo May 1, 2017 at 1:05 pm #

    Hi, an alternative is to use zram: I was able to build dlib with 750MB or zram. Just switch to a text mode runlevel, stop every memory hungry process and you are good to go. I used a config similar to this one (but with 750):

    https://gist.github.com/sultanqasim/79799883c6b81c710e36a38008dfa374

    Had the same speed problem though. I think I’ll use openCV for a quick detection on the Pi, forward the valid frames to a remote server and handle the false positive, alignment, etc, with a second pass of detection with dlib.
    Still have to try the neon optimizations, if I figure out how, but I do not expect miracles.

    https://github.com/davisking/dlib/issues/276

    Wait, it seems like they commited a neon improvement two days ago!

    https://github.com/davisking/dlib/issues/557

    Now they only need to add multi-core support 🙂

    • Adrian Rosebrock May 1, 2017 at 1:11 pm #

      Thank you for sharing your solution Lorenzo!

  2. Renic May 3, 2017 at 3:18 am #

    We will be waiting for your next post anxiously, please don’t make us wait 🙂

    • Adrian Rosebrock May 3, 2017 at 5:37 pm #

      Thanks Renic, it will be a great blog post!

  3. Sandara Park May 3, 2017 at 2:18 pm #

    Hi, I followed the instructions step by step, but when I trying to do “pip install scipy” and “pip install scikit-image” on rapsberry pi, it always shows errors like “Failed building wheel for pillow”, “Failed building wheel for scipy”…….sth like that. So what can I do?

    • Adrian Rosebrock May 3, 2017 at 5:33 pm #

      Hey Sandra — what is the error message you are getting when trying to install scikit-image and the SciPy dependency? I’m guessing you’re running out of RAM, in which case do:

      $ pip install scikit-image –no-cache-dir

      And see if that helps resolve the issue.

  4. Thimira Amaratunga May 5, 2017 at 2:47 am #

    Awesome!
    I was thinking there’s no way Dlib will work on a Raspberry PI.
    Thanks for showing how to get it working. This opens up a lot of possibilities for me.

    I was trying to figure out a way to have multiple cameras connected to process faces.
    Now I can try a set of Raspberry Pis with the camera modules attached, do the pre-processing on them, and send the results to a central node for further processing.

    Thanks again.

    • Adrian Rosebrock May 8, 2017 at 12:39 pm #

      Thanks Thimira, I appreciate the comment 🙂 Congrats on getting dlib installed on your Raspberry Pi!

  5. delta1071 May 6, 2017 at 1:40 pm #

    Hi Adrian,
    Thanks for another awesome, easy-to-follow tutorial. After successfully compiling dlib and verifying the install via Python, I have tried to run the script in both my cv and dlib_python3 virtual environments. In the cv env.,the script errors out with a “no module named dlib” message. In my dlib virtual env.,I’m getting a “no module named cv” error. I’m not sure if this is a symlink issue (I’m sure my cv2.so file is properly linked), or if something else is going on. Any ideas? Thank you.

    • Adrian Rosebrock May 8, 2017 at 12:29 pm #

      This sounds like a sym-link issue for sure. Double and triple-check that you have correctly sym-linked in your cv2.so file into your dlib_python3 virtual environment.

      • hoho May 15, 2017 at 10:52 am #

        have same problem how can I fix it?

      • Jesse Wiklanki May 16, 2017 at 1:15 pm #

        How is that accomplished. Also I am using python 2

        • Adrian Rosebrock May 17, 2017 at 9:56 am #

          You need to check the site-packages directory of your Python virtual environment and ensure that the cv2.so file points to your global install of OpenCV. For more information, please see my tutorials on installing OpenCV on the Raspberry Pi. I would also suggest reading up on how sym-links work.

  6. Shital May 6, 2017 at 2:15 pm #

    Hello, i followed all the steps correctly, and got succeeded in every step but my opencv and dlib not working together,

    Can you please help me

    • Adrian Rosebrock May 8, 2017 at 12:28 pm #

      Can you elaborate more on what you mean by “opencv and dlib are not working together”?

  7. Guy T May 8, 2017 at 8:59 am #

    to solve scipy and scikit-image errors i used apt-get:
    sudo apt-get install python-scipy
    sudo apt-get install python-skimage

    Thank you very much Adrian!!
    cant wait for the post about boosting up dlib on RPI!

    • Adrian Rosebrock May 8, 2017 at 12:16 pm #

      Hi Guy — I WOULD NOT recommend installing SciPy and scikit-image this way if you are using Python virtual environments. Using apt-get to install these libraries will install them globally on your system AND they could potentially be out of date. Use pip instead:

  8. jorge May 18, 2017 at 10:02 am #

    thank very much.

    I been learning a lot with your blog, now I had installed opencv and dlib in RPi noticine the speed issue.

    So for a real time facia application to detect micro-expressions the best is going with what architecture.

    Thank for the advice.

    • Adrian Rosebrock May 18, 2017 at 11:46 am #

      For detecting facial expressions or emotions I would recommend training a custom emotion recognizer. I detail how to do train a custom facial expression recognizer inside Deep Learning for Computer Vision with Python.

  9. Tom May 20, 2017 at 5:59 pm #

    Hi Adrian,
    Using similar method (just by increasing swap space) I have successfully installed dlib on RPi using cmake by following your tutorial for doing it on desktop (it probably was the guru’s course). Just today I came across https://github.com/davisking/dlib/issues/557 where backercp shares his performance tests (HOG’s) for different compilation flags when building C apps. When he is enabling “-O3 -mfpu=neon -fprofile-use” there’s an over 6x speed boost! Would you have any advice about how to prepare dlib “installation” on RPi with these flags enabled?
    Thanks,
    Tom

    • Adrian Rosebrock May 21, 2017 at 5:08 am #

      Hi Tom — optimizing dlib for the Raspberry Pi will likely be a blog post in the future. I’m in the process of compiling and putting together a list of performance tips and tricks.

      • gaurav gupta August 14, 2017 at 4:12 am #

        Hi Adrian,

        Have you completed this ?

        • Adrian Rosebrock August 14, 2017 at 1:08 pm #

          I have not had a chance to write the updated blog post for the Raspberry Pi as I’ve been busy working on the new deep learning book. I will try to make the post more of a priority.

  10. yewon May 21, 2017 at 2:11 am #

    Thank you for your tutorials! I can download dlib successfully (in virtualenv) and reset my swapfile size, boot option, memory split. But when i run the code(pi_facial_landmark.py) in virtualenv, error occurs! “no module named imutils”.
    So I installed the imutils with “pip install –upgrade imutile”.
    And then, I run the code again. Although i install the imutils, it also occur error like “no module named imutils”

    • Adrian Rosebrock May 21, 2017 at 5:06 am #

      Did you make sure you installed imutils inside your virtual environment? You can confirm this via pip freeze

  11. June May 29, 2017 at 6:57 am #

    Hi~
    I’m wating for your post(drowsiness detection on rpi3)
    When i can see your post?
    thanks

    • Adrian Rosebrock May 31, 2017 at 1:22 pm #

      Hi June — I haven’t written the post yet, but it’s in my queue.

  12. Damian June 4, 2017 at 11:34 pm #

    I get errors with Access denied ir permission denied when trying to mkdir for virtualenviroment , scikit-image And dlib installing :/

    • Adrian Rosebrock June 6, 2017 at 12:05 pm #

      Make sure you are logged in as the “pi” user and that you are not trying to install the libraries globally on your system (in which case you would need sudo permissions). This is likely why you are getting the permissions error.

  13. Shivani Junawane July 26, 2017 at 4:04 pm #

    When is your next bolg post – drowsiness detection while driving a motor vehicle coming… What date?… Eagerly waiting. .

    • Adrian Rosebrock July 28, 2017 at 9:58 am #

      Hi Shivani — the driver drowsiness detection post was posted way back on May 8th. You can read it here.

Leave a Reply