Install OpenCV Docker Image on Ubuntu, MacOS or Windows

In this post, we are sharing Docker image for OpenCV 3.4.3, and the recently released OpenCV 3.4.4 and OpenCV 4.0. In addition to OpenCV, the image also has dlib and a Facial Landmark Detection example code.

Every day we receive a few emails and comments on our posts about OpenCV and Dlib installation. Even with the detailed and tested instructions, sometimes it is tough for people to get a system up and running. So, we have been thinking of providing a solution for people who have struggled with installation issues.

One way to solve this problem is to provide a Virtual Machine (VM) with all the libraries installed. A huge downside of using a VM is the large file people need to download. Sometimes it can be 10s of GBs.

A smarter and newer way to solve this problem is to provide a Docker image. Typically a Docker image size is much smaller than a VM. Our Docker image, for example, is just 1 GB in size (compressed size). In addition, it starts much faster than a VM and typically runs applications much faster compared to a VM. Docker is just one of those minimal things that can make your life exceedingly simple.

Also, as we’ll see, the same docker image can be used on Windows, Ubuntu and MacOS. If you are stuck with OpenCV installation or if you want to try out the new OpenCV-3.4.4 and OpenCV-4.0 ( released on 20th November 2018 ), without actually installing it on your system, this docker image is the perfect match for you.

This post is split into five sections

1. Section 1: How to install Docker on Linux, MacOS and Windows.
2. Section 2: How to use Docker image for OpenCV. This image also comes with dlib pre-installed.
3. Section 3: How to run Facial Landmark Detection demo code on Docker Image
4. Section 4: How to make changes to a Docker image.

1. Docker Installation

In this section, we will learn how to install Docker on Ubuntu, MacOS, and Windows.

1.1 Installing Docker on Ubuntu

1. To install docker on Ubuntu 16.04, first add the GPG key for the official Docker repository to the system:

   curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
   

2. Add the Docker repository to APT sources:

   sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
   

3. Next, update the package database with the Docker packages from the newly added repo:

   sudo apt-get update
   

4. Make sure you are about to install from the Docker repo instead of the default Ubuntu 16.04 repo:

   apt-cache policy docker-ce
   

5. You should see output similar to the following:

   docker-ce:
     Installed: (none)
     Candidate: 17.03.1~ce-0~ubuntu-xenial
     Version table:
        17.03.1~ce-0~ubuntu-xenial 500
           500 https://download.docker.com/linux/ubuntu xenial/stable amd64 Packages
        17.03.0~ce-0~ubuntu-xenial 500
           500 https://download.docker.com/linux/ubuntu xenial/stable amd64 Packages
   

6. Finally, install Docker:

   sudo apt-get install -y docker-ce
   

1.2 Installing on MacOS

1. To install Docker on MacOS desktop, first go to the Docker Store and download Docker Community Edition for Mac.
2. Double-click Docker.dmg to open the installer, then drag Moby the whale to the Applications folder.
3. Double-click Docker.app in the Applications folder to start Docker.
4. You are prompted to authorise Docker.app with your system password after you launch it. Privileged access is needed to install networking components and links to the Docker apps.

The whale in the top status bar indicates that Docker is running, and accessible from a terminal.

1.3 Installing Docker Toolbox in Windows 7 or above

1. Download and install Docker Toolbox for Windows. The installer adds Docker Toolbox, VirtualBox, and Kitematic to your Applications folder.
2. On your Desktop, find the Docker QuickStart Terminal icon.
3. Double click the Docker QuickStart icon to launch a pre-configured Docker Toolbox terminal.

bash
Running pre-create checks...
(default) No default Boot2Docker ISO found locally, downloading the latest release...
(default) Latest release for github.com/boot2docker/boot2docker is v18.06.1-ce
(default) Downloading C:\Users\imsau\.docker\machine\cache\boot2docker.iso from https://github.com/boot2docker/boot2docker/releases/download/v18.06.1-ce/boot2docker.iso

4. Press enter and the installation will be automatically started. Once done, the file will be present in

   \users\username\.docker\machine\cache\boot2docker.iso.



5. If the system displays a User Account Control prompt to allow VirtualBox to make changes to your computer, choose Yes.
   The terminal does several things to set up Docker Toolbox for you. When it is done, the terminal displays the $ prompt.

2 Install Docker OpenCV Image

To use the docker image, use the following instructions:

docker pull spmallick/opencv-docker:opencv

Once, the image is downloaded, we can start it using the following command

docker run --device=/dev/video0:/dev/video0 -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY -p 5000:5000 -p 8888:8888 -it spmallick/opencv-docker:opencv /bin/bash

Let’s take a moment to examine this command in detail:

• –device=/dev/video0:/dev/video0 allows use of webcam
• -v /tmp/.X11-unix:/tmp/.X11-unix helps in X11 forwarding so that we can use functions like cv::imshow.
• -e is used to pass an environment variable.
• -it starts an interactive session
• -p sets up a port forward. This flag maps the container’s port to a port on the host system.
• /bin/bash runs .bashrc file on startup

The image has OpenCV 3.4.3 installed in /usr/local, OpenCV 3.4.4 in ~/installation/OpenCV-3.4.4 and OpenCV 4.0.0 in ~/installation/OpenCV-master.

To use Python environments:
For OpenCV 3.4.3,

workon OpenCV-3.4.3-py3
ipython

Once you are in the iPython prompt, do

import cv2
cv2.__version__
exit()

To deactivate the virtual environment use

deactivate

Similarly for OpenCV 3.4.4 and OpenCV 4.0.0,

 
workon OpenCV-3.4.4-py3
ipython

Once you are in the iPython prompt, do

 
import cv2
cv2.__version__
exit()

To deactivate the virtual environment type

 
deactivate

workon OpenCV-master-py3
ipython

Once you are in the iPython prompt, do

 
import cv2
cv2.__version__
exit()

3 Run Facial Landmark Detection on Docker Image

To test the installation of OpenCV and dlib on the docker image, we have provided a Facial Landmark detection example that you can try out.

1. First, we make sure that we have the latest docker image.

   docker pull spmallick/opencv-docker:opencv
   

2. Next, we run the docker image as specified in the earlier sections.

   docker run --device=/dev/video0:/dev/video0 -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY -p 5000:5000 -p 8888:8888 -it spmallick/opencv-docker:opencv /bin/bash
   

3. Once the docker container is created and is running, you will find 3 folders in /root/ – common, demo and installation. The demo folder contains C++ and Python version of the Facial Landmark Detection code.
4. To run the Python script, follow the steps given below. The instructions are for OpenCV-4.0.0. For OpenCV-3.4.3 and OpenCV-3.4.4 just change the environment as discussed earlier.

   cd ~/demo/python
   

   source activate OpenCV-master-py3
   python facialLandmarkDetector.py
   source deactivate
   

5. To run the C++ code, follow the steps given below:

   cd ~/demo/cpp/
   

   You will find 3 folders, one for each OpenCV version installed. The CMakeLists.txt file present in the folders can be used as a reference for building codes for that particular OpenCV version.

   cd OpenCV-3.4.4/build
   cmake ..
   cmake --build . --config Release
   cd ..
   ./build/facialLandmarkDetector
   

4 How to commit changes to Docker Image

To commit changes made to the docker image, we need to follow the steps below. We will refer to the image of the terminal below as an example

1. Find the Container ID: The easiest way to find it out is to note the text following [email protected] in your docker container. For example, in the image above, the docker container ID is 56a07cf4614c. Also, note that Container ID will vary every time you use docker run to create a new container.
2. Make a change: In the example above, we create a simple file HelloUser.sh that outputs some text when run from the command line.
3. Exit: Once the changes have been made, we need to exit the container using exit command.
4. Commit changes: Finally, to commit the changes made to the docker image use the following command

   sudo docker commit CONTAINER_ID NAME_OF_DOCKER_IMAGE
   

   In our example, we use

   sudo docker commit 56a07cf4614c my-docker-image
   

5. Check image: You want to make sure the committed docker image shows up when you run the following command

   docker images
   

6. Use image: Next time when you want to use this docker image, just use the following command:

   docker run --device=/dev/video0:/dev/video0 -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY -p 5000:5000 -p 8888:8888 -it NAME_OF_DOCKER_IMAGE /bin/bash
   

   In our specific example, we use

   docker run -u 0 -it -p 8888:8888 -p 5000:5000 my-docker-image /bin/bash
   

Hope you have fun hacking with Docker! 🙂 If you have any queries, comment below and we will get back to you as soon as possible.

Subscribe & Download Code

If you liked this article and would like to download code (C++ and Python) and example images used in other posts of this blog, please subscribe to our newsletter. You will also receive a free Computer Vision Resource Guide. In our newsletter, we share OpenCV tutorials and examples written in C++/Python, and Computer Vision and Machine Learning algorithms and news.

Subscribe Now

References

1. Docker for Data Science: Building Scalable and Extensible Data Infrastructure Around the Jupyter Notebook Server by Joshua Cook
2. Techrepublic: How to commit changes to a docker image