Title: Install dlib on the Raspberry Pi - PyImageSearch

URL Source: https://pyimagesearch.com/2017/05/01/install-dlib-raspberry-pi/

Published Time: 2017-05-01T14:00:45+00:00

Markdown Content:
![Image 1](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20600%20241'%3E%3C/svg%3E)

A few weeks ago I did a blog post on [how to install the dlib library on Ubuntu and macOS](https://pyimagesearch.com/2017/03/27/how-to-install-dlib/).

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._**

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](https://pyimagesearch.com/2017/03/27/how-to-install-dlib/) to install dlib on your Raspberry Pi, your compile likely bombed out with an error message similar to this one:

![Image 2](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20600%20367'%3E%3C/svg%3E)

**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](http://neil.franklin.ch/Projects/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:

$ sudo nano /etc/dphys-swapfile

Scroll down to the configuration which reads:

`CONF_SWAPSIZE=100`

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

![Image 3](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20600%20588'%3E%3C/svg%3E)

**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](https://www.bitpi.co/2015/02/11/how-to-change-raspberry-pis-swapfile-size-on-rasbian/)._

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

$ sudo /etc/init.d/dphys-swapfile stop
$ sudo /etc/init.d/dphys-swapfile start

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:

$ free -m

To confirm that your swap size has been increased.

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

![Image 4](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20600%20256'%3E%3C/svg%3E)

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:

$ sudo raspi-config

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

![Image 5](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20600%20369'%3E%3C/svg%3E)

**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:

![Image 6](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20600%20368'%3E%3C/svg%3E)

**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:

$ sudo apt-get update
$ sudo apt-get install build-essential cmake
$ sudo apt-get install libgtk-3-dev
$ sudo apt-get install libboost-all-dev

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:

$ wget https://bootstrap.pypa.io/get-pip.py
$ sudo python get-pip.py

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](https://virtualenv.pypa.io/en/latest/) and [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/) 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](https://pyimagesearch.com/opencv-tutorials-resources-guides/) along with this excellent [Python virtual environment primer](https://realpython.com/blog/python/python-virtual-environments-a-primer/).

If you would like to install dlib into a _pre-existing_ Python, virtual environment, use the `workon` command:

$ workon <your virtualenv name>

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

$ workon cv

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:

$ mkvirtualenv py2\_dlib

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

$ mkvirtualenv py3\_dlib -p python3

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](http://scikit-image.org/), a library commonly used in conjunction with dlib:

$ pip install numpy
$ pip install scipy
$ pip install scikit-image

We can then install dlib via `pip` as well:

$ pip install dlib

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

![Image 7](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20600%20241'%3E%3C/svg%3E)

**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` :

$ python
Python 3.4.2 (default, Oct 19 2014, 13:31:11) 
\[GCC 4.9.1\] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> 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:

\# import the necessary packages
from imutils import face\_utils
import dlib
import cv2

# initialize dlib's face detector (HOG-based) and then create
# the facial landmark predictor
p = "shape\_predictor\_68\_face\_landmarks.dat"
detector = dlib.get\_frontal\_face\_detector()
predictor = dlib.shape\_predictor(p)

# load the input image and convert it to grayscale
image = cv2.imread("example.jpg")
gray = cv2.cvtColor(image, cv2.COLOR\_BGR2GRAY)

# detect faces in the grayscale image
rects = detector(gray, 0)

# loop over the face detections
for (i, rect) in enumerate(rects):
	# determine the facial landmarks for the face region, then
	# convert the facial landmark (x, y)-coordinates to a NumPy
	# array
	shape = predictor(gray, rect)
	shape = face\_utils.shape\_to\_np(shape)

	# loop over the (x, y)-coordinates for the facial landmarks
	# and draw them on the image
	for (x, y) in shape:
		cv2.circle(image, (x, y), 2, (0, 255, 0), -1)

# show the output image with the face detections + facial landmarks
cv2.imshow("Output", image)
cv2.waitKey(0)

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](https://pyimagesearch.com/2017/04/03/facial-landmarks-dlib-opencv-python/).

To execute the script:

*   Make sure you’ve installed/upgraded the [imutils library](https://github.com/jrosebr1/imutils) 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:

$ python pi\_facial\_landmarks.py

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

![Image 8](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20600%20375'%3E%3C/svg%3E)

**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](https://pyimagesearch.com/2017/04/17/real-time-facial-landmark-detection-opencv-python-dlib/). 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](https://pyimagesearch.com/2016/01/04/unifying-picamera-and-cv2-videocapture-into-a-single-class-with-opencv/). 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](http://www.learnopencv.com/speeding-up-dlib-facial-landmark-detector/) — 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.

### What's next? We recommend [PyImageSearch University](https://pyimagesearch.com/pyimagesearch-university/?utm_source=blogPost&utm_medium=bottomBanner&utm_campaign=What%27s%20next%3F%20I%20recommend).

**Course information:**  
84 total classes • 114+ hours of on-demand code walkthrough videos • Last updated: February 2024  
★★★★★ 4.84 (128 Ratings) • 16,000+ Students Enrolled

**I strongly believe that if you had the right teacher you could _master_ computer vision and deep learning.**

Do you think learning computer vision and deep learning has to be time-consuming, overwhelming, and complicated? Or has to involve complex mathematics and equations? Or requires a degree in computer science?

That’s _not_ the case.

All you need to master computer vision and deep learning is for someone to explain things to you in _simple, intuitive_ terms. _And that’s exactly what I do_. My mission is to change education and how complex Artificial Intelligence topics are taught.

If you're serious about learning computer vision, your next stop should be PyImageSearch University, the most comprehensive computer vision, deep learning, and OpenCV course online today. Here you’ll learn how to _successfully_ and _confidently_ apply computer vision to your work, research, and projects. Join me in computer vision mastery.

**Inside PyImageSearch University you'll find:**

*   ✓ **84 courses** on essential computer vision, deep learning, and OpenCV topics
*   ✓ **84 Certificates** of Completion
*   ✓ **114+ hours** of on-demand video
*   ✓ **Brand new courses released _regularly_**, ensuring you can keep up with state-of-the-art techniques
*   ✓ **Pre-configured Jupyter Notebooks in Google Colab**
*   ✓ Run all code examples in your web browser — works on Windows, macOS, and Linux (no dev environment configuration required!)
*   ✓ Access to **centralized code repos for _all_ 536+ tutorials** on PyImageSearch
*   ✓ **Easy one-click downloads** for code, datasets, pre-trained models, etc.
*   ✓ **Access** on mobile, laptop, desktop, etc.

[Click here to join PyImageSearch University](https://pyimagesearch.com/pyimagesearch-university/?utm_source=blogPost&utm_medium=bottomBanner&utm_campaign=What%27s%20next%3F%20I%20recommend)

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:

![Image 9](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20333%20203'%3E%3C/svg%3E)

**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!_**

![Image 10](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20410%20567'%3E%3C/svg%3E)

#### Download the Source Code and FREE 17-page Resource Guide

Enter your email address below to get a .zip of the code and a **FREE 17-page Resource Guide on Computer Vision, OpenCV, and Deep Learning.** Inside you'll find my hand-picked tutorials, books, courses, and libraries to help you master CV and DL!