Install dlib (the easy, complete guide)

The latest release of dlib is special.

It completely removes the boost.python dependency, making it significantly easier to install across the board on macOS, Ubuntu, and Raspbian.

Thanks to the work of Davis King (the creator and maintainer of the dlib library) and Mischan Toos-Haus (who is responsible for removing the boost.python dependency), we can now:

  • Easily leverage all Python + dlib functionality (face detection, facial landmarks, correlation tracking, etc.)…
  • …with less dependencies and an easier install process.

In today’s blog post I’ll be providing instructions to install dlib on:

  • macOS
  • Ubuntu
  • Raspbian (Raspberry Pi’s operating system)

These install instructions are complete, easy, to follow, and will get you up and running with dlib + Python bindings in a manner of minutes.

To learn how to install dlib on your system, just keep reading!

Looking for the source code to this post?
Jump right to the downloads section.

Install dlib (the easy, complete guide)

In this guide you’ll learn how to install dlib on macOS, Ubuntu, and Raspbian. Please feel free to skip to the section that corresponds to your operating system.

Once you have installed dlib on your respective operating system we’ll validate the install by using Python, dlib, and OpenCV (provided you have OpenCV installed as well), to detect facial landmarks.

From there, I have provided additional tutorials and guides to help apply dlib to computer vision and machine learning projects, including detecting and counting blinks and building a system to recognize when the driver of a vehicle is becoming drowsy/tired (and alerting them to wake up).

Installing dlib on macOS

I’ll assume you already have XCode installed on your macOS machine. If not, please take the time to open the App Store and install XCode.

From there, you’ll need to install Homebrew, a package manager for macOS, similar to Debian/Ubuntu’s apt-get :

Note: Make sure you use the “<>” button in the code block above to expand section — this will ensure you copy and paste the entire Homebrew install command.

Once Homebrew is installed you need to update your PATH  to look for Homebrew binaries, packages, and libraries. This can be accomplished by manually editing the file using an editor such as nano, vi, etc. or simply using echo  and redirection:

You then need to source  the ~/.bash_profile  file to reload the changes:

We’ll then install cmake  (a utility used for building, testing, and packaging software) along with Python 2.7 and Python 3:

You can verify that Python 2.7 and Python 3 have been successfully installed by using which :

There are two key points you need to pay attention to here.

The first is that you want to ensure the root path for both Python binaries are in /usr/local/bin  — this is where Homebrew stores the Python binaries.

If your root path instead reads /usr/bin  then you are utilizing the system Python install. We want to avoid using the system Python install so if you see /usr/bin  instead of /usr/local/bin  then it’s most likely due to an error updating your ~/.bash_profile  (make sure you go back and ensure the file has been updated properly; this could require manually opening and editing the file).

The second key point to investigate is the Python binary itself: python2  and python3 . Notice how we are not executing just python  — instead we are explicitly supplying the version as well.

This is due to how Homebrew now handles Python installs. In older versions of Homebrew, Homebrew would automatically alias the python  command to either Python 2.7 or Python 3 — this is no longer the case. Instead, we need to explicitly supply the Python version number.

The name is true for pip  as well: we now use pip2  and pip3 .

Next, let’s prepare our Python environment.

If you are using a Python virtual environment (if you followed any of my OpenCV install tutorials, you likely are using them), you can either create a new Python virtual environment for the dlib install:

Or access an existing one:

Using a Python virtual environment is entirely optional but highly recommended as Python virtual environments are a best practice for Python development. To learn more about Python virtual environments (and how to use them) please consult my OpenCV install tutorials where they are covered extensively.

From there, we can install NumPy (dlib’s only Python dependency) followed by the dlib library itself:

If you are not using Python virtual environments you’ll need to update the pip  command to either pip2  or pip3 . If you are using Python 2.7, use pip2  instead of pip . Similarly, if you are utilizing Python 3, replace pip  with pip3 .

From there, fire up a Python shell and validate your install of dlib:

Figure 1: Successfully installing dlib on macOS.

Installing dlib on Ubuntu

The following instructions were gathered on Ubuntu 16.04 but should work on newer versions of Ubuntu as well.

To get started, let’s install our required dependencies:

I have included a few notes on the dependencies that you should consider:

  1. We are installing GTK and X11 for GUI functionality inside dlib. These libraries can be skipped if you do not care about the GUI functionality, saving you 100-200MB in space.
  2. We install OpenBLAS for linear algebra optimizations which allows dlib functionality to execute faster. You can technically skip this as well but I highly recommend you install OpenBLAS as the optimizations are significant.

Next, let’s prepare our Python environment for the dlib install.

If you are using a Python virtual environment (if you followed any of my OpenCV install tutorials, you likely are using them), you can either create a new Python virtual environment for the dlib install:

Or access an existing one:

Using a Python virtual environment is entirely optional but highly recommended as Python virtual environments are a best practice for Python development. To learn more about Python virtual environments (and how to use them) please consult my OpenCV install tutorials where they are covered extensively.

You can then install dlib on your Ubuntu system:

If you are not using a Python virtual environment make sure you add sudo  to the beginning of the pip install  commands (otherwise the pip install  commands will fail due permission errors). Additionally, keep in mind that pip  is used to install packages for Python 2.7 and pip3  is used for Python 3. Depending on which Python version you want to install dlib for you may need to update the pip  command above.

Finally, open up a Python shell and verify your dlib install on Ubuntu by importing the dlib  library:

Figure 2: Installing dlib on Ubuntu (Note: I was SSH’d into an Ubuntu machine in the Amazon EC2 cloud from my macOS machine when taking this screenshot, hence why the screenshot looks like the macOS GUI).

Installing dlib on Raspberry Pi/Raspbian

This section covers installing the dlib library on the Raspberry Pi and the Raspbian Stretch operating system. These instructions should work for newer releases of Rasbpian as well.

Our Raspbian dlib install is identical to our Ubuntu dlib install, but with a few minor adjustments:

  1. Both Python 2.7 and Python 3 are pre-installed on Raspbian so we do not need to install them ourselves.
  2. We need to install libatlas-base-dev .
  3. We can optionally optimize our dlib install on the Raspberry Pi architecture via the USE_NEON_INSTRUCTIONS  switch (this will require you install dlib from source rather than pip ).

Let’s get started installing dlib on our Raspberry Pi by ensuring we have met our library/package dependencies:

A few quick notes on both X11/GTK and OpenBLAS:

  1. We are installing GTK and X11 for GUI functionality inside dlib. These libraries can be skipped if you do not care about the GUI functionality, saving you 100-200MB in space. Space can be a premium on the Raspberry Pi, but again, if you need GUI functionality make sure you install them.
  2. We install OpenBLAS for linear algebra optimizations which allows dlib functionality to execute faster. You can technically skip this as well but I highly recommend you install OpenBLAS as the optimizations are significant — any optimization you can achieve on the Raspberry Pi is well worth it!

Next, let’s prepare our Python environment for the dlib install on our Raspberry Pi.

If you are using a Python virtual environment (if you followed any of my OpenCV install tutorials, you likely are using them), you can either create a new Python virtual environment for the dlib install:

Or access an existing one:

Using a Python virtual environment is entirely optional but highly recommended as Python virtual environments are a best practice for Python development. To learn more about Python virtual environments (and how to use them) please consult my OpenCV install tutorials where they are covered extensively.

We can then install dlib on Raspberry Pi:

If you are not using a Python virtual environment make sure you add sudo  to the beginning of the pip install  commands (otherwise the pip install  commands will fail due permission errors). Additionally, keep in mind that pip  is used to install packages for Python 2.7 and pip3  is used for Python 3. Depending on which Python version you want to install dlib for you may need to update the pip  command above.

If you decide you would like to have the NEON instructions utilized to optimize the dlib install, skip installing dlib via pip  and instead install via source:

Compiling from source will take longer than installing via pip  so be patient.

Finally, open up a Python shell and verify your dlib install on Raspbian by importing the dlib  library:

Note: The dlib install version for the Raspberry Pi is different from my macOS and Ubuntu output as I installed from source to leverage the NEON optimizations rather than installing via pip.

Figure 3: Successfully installing dlib on the Raspberry Pi and Raspbian operating system.

Testing your dlib install

As a final example of using dlib on the Raspberry Pi, here is a short example I put together where we detect facial landmarks in an input image:

Note: This example assumes you have both OpenCV and dlib installed on your system. If you do not have OpenCV installed, please refer to my OpenCV install tutorials.

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

To execute the above script:

  • Make sure you have installed OpenCV, dlib, and imutils ( pip install --upgrade imutils ).
  • Use the “Downloads” section below to download the source code + example image + pre-trained dlib facial landmark predictor.

From there, you can issue the following command to execute our example script:

You should then see the following output where the facial landmarks are displayed on the image:

Figure 4: Detecting facial landmarks using the dlib library and Python.

Fun fact: The picture above is me ~8 years ago during my undergraduate college days. I actually had hair back then!

What now?

Now that you’re up and running with dlib I would recommend you:

  1. Install OpenCV on your system as well (if you haven’t already). I have a number of OpenCV install tutorials for macOS, Ubuntu, and Raspbian available here.
  2. Use your OpenCV + dlib install to build practical, real-world projects.

I would recommend starting with this tutorial where you’ll learn how to apply real-time facial landmark detection:

Figure 5: Using dlib to apply real-time facial landmark detector.

From there, you can utilize facial landmarks to build an eye blink detector:

Figure 6: Building an eye blink detector with dlib, OpenCV, and Python.

And then finally we put all the pieces together from the previous two tutorials to build a drowsiness detector:

Figure 7: Creating a drowsiness detector with dlib, OpenCV, and Python.

Be sure to take a look at the tutorials! They are fun, hands-on, and will give you a ton of experience building real-world computer vision applications with dlib and OpenCV.

Summary

In today’s blog post you learned how to install dlib on macOS, Ubuntu, and Raspbian.

Thanks to the work of Davis King and Mischan Toos-Haus it is now easier than ever to install dlib, requiring less dependencies and a faster pip install  process.

Take a second now to give both Davis and Mischan a huge thanks for their hard work and their contributions to the open source community.

I hope you enjoyed this blog post! To be notified when future PyImageSearch tutorials are published, 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 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! Sound good? If so, enter your email address and I’ll send you the code immediately!

, , , , ,

41 Responses to Install dlib (the easy, complete guide)

  1. Anthony The Koala January 22, 2018 at 11:09 am #

    Dear Dr Adrian,
    For those with MS Operating systems, it is easy to install It assumes that your Python system has been installed.
    * Open a DOS shell
    * type the following command:

    pip install dlib

    * suppose you are in the python shell, say in the MS version, “Idle”, type:
    import dlib
    dlib.__version__
    ‘19.4.0’

    Regards
    Anthony of Sydney

    • Adrian Rosebrock January 22, 2018 at 4:36 pm #

      Thanks for sharing, Anthony! 🙂

    • Jette January 23, 2018 at 2:39 pm #

      Thank you!
      Although I had to use “pip install cmake” and install “Visual C++ 2015 Build Tools” first, but it worked out in the end 🙂

  2. Steven January 22, 2018 at 11:39 am #

    Hi Adrian,

    I tried to use “pip install dlib” and successfully download dlib, but I got cmake error (Could NOT find Threads (missing: Threads_FOUND). Is there any method I can take to solve this issue?

    Thanks.

    • Adrian Rosebrock January 22, 2018 at 4:35 pm #

      Hey Steven — which operating system are you on?

      • Steven January 22, 2018 at 7:35 pm #

        I use Mac OSX.

        • Adrian Rosebrock January 23, 2018 at 2:05 pm #

          Thanks for the extra information, Steven. Unfortunately I’m not sure what would be causing that error. I would suggest posting on the official dlib GitHub Issues page where the developers can likely offer more insight.

          • Steven January 23, 2018 at 2:56 pm #

            Thanks for your reply. I’ll try to report that.

  3. Nuel Ezenwere January 22, 2018 at 11:54 am #

    Thanks for the update Adrain.

    • Adrian Rosebrock January 22, 2018 at 4:35 pm #

      Happy to share, Nuel! 🙂

  4. Emanuel R Woiski January 22, 2018 at 4:22 pm #

    The easiest installation ever: With Anaconda. Python 3.6 and Ubuntu 16.04, I’ve installed dlib and pre-built opencv-contrib-python 3.4.0.12 using pip. Your facial_landmarks.py run just fine.

    • Adrian Rosebrock January 22, 2018 at 4:35 pm #

      Congrats on getting up and running with dlib and OpenCV, Emanuel! Nice job.

  5. nidhi January 23, 2018 at 3:27 am #

    Traceback (most recent call last):
    File “facial_landmarks.py”, line 5, in
    from imutils import face_utils
    ImportError: No module named ‘imutils

    I get this error when i run python facial_landmarks.py

    any help?

    • Adrian Rosebrock January 23, 2018 at 1:59 pm #

      You need to install the “imutils” library:

      $ pip install imutils

      • nidhi January 24, 2018 at 10:39 pm #

        thanks!!!!

  6. charles January 24, 2018 at 7:54 am #

    Dr.Adrian,
    I have installed dlib as you instructed.
    I am getting version of dlib in interpreter as well.

    But When I’m running test program, facial_landmarks.py I am getting this

    Traceback (most recent call last):
    File “dlibdemo.py”, line 10, in
    predictor = dlib.shape_predictor(p)
    RuntimeError: Unable to open shape_predictor_68_face_landmarks.dat

    Thanks in advance

    • Adrian Rosebrock January 24, 2018 at 4:53 pm #

      You need to use the “Downloads” section of this blog post to download the source code + shape_predictor_68_face_landmarks.dat file. From there, change directory to the download location and execute the facial landmarks script.

  7. Norman Whitehead January 25, 2018 at 11:30 am #

    I installed imutils and got :

    error: could not create ‘/usr/local/lib/python2.7/dist-packages/imutils’: Permission denied

    Why permission denied?

    • Adrian Rosebrock January 25, 2018 at 3:41 pm #

      If you’re installing imutils (or any other packages) in the site-packages directory of the system Python install you need sudo permission:

      $ sudo pip install imutils

  8. Curtis January 28, 2018 at 7:43 pm #

    I want to use dlib’s gui features, like image_window(). I didn’t see any way to do it without building it myself It’s not too bad, I’m on Mac OS X, here’s what I did:

    brew cask install xquartz
    git clone https://github.com/davisking/dlib.git
    cd dlib
    mkdir build
    cd build
    cmake –build .

    Then, in your virtualenv shell:

    cd dlib
    python setup.py install

    • Adrian Rosebrock January 30, 2018 at 10:20 am #

      Awesome, thanks for sharing Curtis!

  9. alicia March 1, 2018 at 10:36 am #

    hello I followed the steps and installed dlib in a virtual environment with opencv 3.3 ( ubuntu 16.04) ,the Dlib installation indicates successful installation but when importing dlib the module is not found, What could be the problem?

    screenshot
    http://i68.tinypic.com/20f6byo.png

    thanks

    • Adrian Rosebrock March 2, 2018 at 10:43 am #

      Look at your “pip freeze” it appears that dlib is not actually installed. Make sure you run:

      $ pip install dlib

      And ensure the compile + install process completes successfully.

  10. kaisar khatak May 19, 2018 at 12:06 am #

    Thank you for the blog post. Dlib is cool. I was wondering what is the best way to capture the mouth area (between the lips) using opencv/dlib?

    Example app: when a user opens their mouth, I would like to color the mouth green for example.

    One approach is to put a rectangle around the mouth region and use threshholding and find contours (largest = mouth?). What approach do you recommend?

    • Adrian Rosebrock May 22, 2018 at 6:28 am #

      You could compute the convex hull of the mouth region. This would give you the complete area of the mouth.

  11. Ashwin June 26, 2018 at 1:58 am #

    any ideas on how to get dlib up and running on windows. followed the steps to get dlib for windows but even after successful installation the program doesnt seem to execute. throws error with the dlib library

    • Adrian Rosebrock June 28, 2018 at 8:23 am #

      Hey Ashwin, if you are having trouble installing or using dlib on Windows I would suggest posting on the dlib GitHub Issues page.

  12. musadiq July 8, 2018 at 3:02 pm #

    usage: detect_blinks.py [-h] -p SHAPE_PREDICTOR [-v VIDEO]
    detect_blinks.py: error: argument -p/–shape-predictor is required

    how to fix this?

  13. HudsA July 14, 2018 at 9:21 pm #

    Hi Adrian,

    I followed every step, and too the steps Opencv, but I had problem during “python facial_landmarks.py”. I receive the following message:

    ImportError: No module named cv2

    Help me, please.

    • Adrian Rosebrock July 17, 2018 at 7:28 am #

      It sounds like you do not have OpenCV installed on your system. Are you using Python virtual environments? If so, are you inside the environment? And did you install dlib into the Python virtual environment you used for OpenCV or a different one?

  14. Oanh Nguyen August 2, 2018 at 3:05 am #

    Hi Adiran,
    When I using cmake to compile Dlib, how can I enable NEON optimization?
    Thanks!

    • Adrian Rosebrock August 2, 2018 at 9:20 am #

      I believe it should be the -mfpu=neon switch but you should check the official dlib GitHub/documentation.

  15. vamshi August 7, 2018 at 3:34 am #

    Thank you so much Adrian..Installed dlib in my Raspberry Pi 3b+ successfully Using the swap method and it took me 75 mins to install.

    • Adrian Rosebrock August 7, 2018 at 6:27 am #

      Congrats on getting dlib installed on your Pi, Vamshi!

  16. Akhil August 27, 2018 at 7:29 am #

    Hi Adrian

    I have installed Ubuntu 16,04 in my system with no GPU support and I am trying to build dlib from source code as per the link

    https://gist.github.com/ageitgey/629d75c1baac34dfa5ca2a1928a7aeaf

    But whenever I am executing the command :-

    python3 setup.py install –yes USE_AVX_INSTRUCTIONS –no DLIB_USE_CUDA

    The system is getting hanged and I need to restart the system again.

    Any help would be great

    Regards
    Akhil

    • Adrian Rosebrock August 30, 2018 at 9:18 am #

      Hey Akhil — it’s odd that your system is hanging. How much RAM does your system have? Is it a new-ish machine?

  17. reza September 1, 2018 at 6:59 am #

    hi Adrian.thank you so much for your excellent post.please help me to install dlib package on windows.i can’t follow your posts cuz i can’t install dlib library on windows

    • Adrian Rosebrock September 5, 2018 at 9:11 am #

      Hey Reza, thanks for the comment; however, I must admit that I do not support Windows here on the PyImageSearch blog. If you are interested in computer vision and deep learning I would highly suggest you use a Unix-based machine such as Linux (Ubuntu) or macOS.

  18. reza September 6, 2018 at 4:50 pm #

    so there isn’t any solution for installing dlib library on windows?

    • Adrian Rosebrock September 11, 2018 at 8:36 am #

      Only unofficial ones.

Leave a Reply