pip install opencv

In this tutorial you will will learn how to pip install OpenCV on Ubuntu, macOS, and the Raspberry Pi.

In previous OpenCV install tutorials I have recommended compiling from source; however, in the past year it has become possible to install OpenCV via pip, Python’s very own package manager.

While installing from source will give you the greatest control over your OpenCV configuration, it’s also the hardest and the most time consuming.

If you’re looking for the fastest possible way to install OpenCV on your system, you want to use pip to install OpenCV (but there are a few things that may trip you up along the way, so make sure you read the rest of this guide).

To learn how to pip install OpenCV on your system, just keep reading.

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

pip install opencv

In the remainder of this tutorial I’ll briefly describe the OpenCV packages you can install via pip, Python’s package manager.

From there, I’ll demonstrate how to pip install OpenCV on Ubuntu, macOS, and the Raspberry Pi.

Finally, I’ll review some common problems you may encounter when using pip to install OpenCV.

I’d like to point out an important caveat to this OpenCV installation method before we begin.

The PyPi/PiWheels hosted versions of OpenCV that we’re discussing today do not include “non-free” algorithms such as SIFT, SURF, and other patented algorithms. This is a great method to install OpenCV if you need a quick environment in which you won’t need to run programs containing the non-free algorithms — if that’s not the case, you’ll need to complete a full compile of OpenCV.

The two pip OpenCV packages: opencv-python and opencv-contrib-python

Before we get started I want to remind you that the methods I’m coming here today are unofficial pre-built OpenCV packages that can be installed via pip — they are not official OpenCV packages released by OpenCV.org.

Just because they are not official packages doesn’t mean you should feel uncomfortable using them, but it’s important for you to understand that they are not endorsed and supported directly by the official OpenCV.org team.

All that said — there are four OpenCV packages that are pip-installable on the PyPI repository:

  1. opencv-python: This repository contains just the main modules of the OpenCV library. If you’re a PyImageSearch reader you do not want to install this package.
  2. opencv-contrib-python: The opencv-contrib-python repository contains both the main modules along with the contrib modules — this is the library I recommend you install as it includes all OpenCV functionality.
  3. opencv-python-headless: Same as opencv-python but no GUI functionality. Useful for headless systems.
  4. opencv-contrib-python-headless: Same as opencv-contrib-python but no GUI functionality. Useful for headless systems.

Again, in the vast majority of situations you will want to install opencv-contrib-python  on your system.

You DO NOT want to install both opencv-python  and opencv-contrib-python  — pick ONE of them.

How to pip install OpenCV on Ubuntu

You have two options to install OpenCV on Ubuntu with pip:

  1. Install into your system site-packages
  2. Install into a virtual environment’s  site-packages  (preferred)

First, install pip

If you don’t have pip, you’ll need to obtain it first:

Option A: Install OpenCV to your Ubuntu system with pip

I wouldn’t recommend this method unless you have a particular use case where you don’t want isolated, independent Python environments.

Let’s pip install opencv-contrib-python on our system:

In a matter of seconds, OpenCV is ready to go in your system’s site-packages!

Option B: Install OpenCV on Ubuntu into a virtual environment with pip

There are huge benefits to Python virtual environments.

The main benefit is that you can develop multiple projects on your system with isolated packages (many with version dependencies) without having to muddy the waters of your system.  You’re also free to add and remove virtual environments as you go.

Put simply: Python virtual environments are a best practice for Python development. Chances are, you should jump on the bandwagon.

My tools of choice are virtualenv  and virtualenvwrapper  but you could choose an alternative such as venv or Anaconda (conda for short).

Here’s how to install virtualenv  and virtualenvwrapper , both of which will live in your system site-packages  and manage each project’s virtual environment site-packages:

Before we can continue, you first need to add some lines to your ~/.bashrc  profile. Open the file using nano , vim , or emacs  and append these lines to the end:

Save the file. Then “source it” in your terminal:

You’ll see some terminal output which sets up virtualenvwrapper. You now have access to new terminal commands:

  • Create an environment with mkvirtualenv .
  • Activate an environment (or switch to a different one) with workon .
  • Deactivate an environment with deactivate .
  • Remove an environment with rmvirtualenv .
  • Be sure to read the docs!

Let’s create a Python 3 virtual environment for OpenCV called cv:

And now with a magic wand (pip), you can pip install OpenCV in a matter of seconds into your new environment:

How to pip install OpenCV on macOS

MacOS is similar to Ubuntu for pip-installing OpenCV.

Again, you have two options to install OpenCV on macOS with pip:

  1. Install into your system site-packages
  2. Install into a virtual environment’s  site-packages  (preferred)

Install pip

If you don’t have pip, you’ll need to obtain it first:

Option A: Install OpenCV to your macOS system with pip

Don’t do this.

Why? I actually recommend that you go to the Option B and use a virtual environment.

Okay, well if you insist on installing on your macOS system, then it’s just as easy as pip installing OpenCV via:

In a matter of seconds, OpenCV is ready to go in your system’s site-packages.

Option B: Install OpenCV on macOS into a virtual environment with pip

Just like managing packages is a breeze with pip….

…managing projects and their dependencies is a breeze with virtual environments.

You should use Python virtual environments if you’re serious about computer vision development (or any development for that matter).

I don’t care what system you use (be it virtualenv , venv , or conda  /Anaconda), just learn to use one and stick with it.

Here’s how to install virtualenv and virtualenvwrapper, both of which will live in your system site-packages and manage each project’s virtual environment site-packages:

From there, you need to add the following lines to your ~/.bash_profile  (notice that for macOS the file name is .bash_profile  and for Ubuntu it is .bashrc .

Open the file using nano , vim , or emacs  ( nano  comes on most systems):

…and append these lines to the end:

Save the file — if you are using nano  the keyboard shortcuts are listed at the bottom of the window.

Then “source it” in your terminal:

You’ll see a few lines of terminal output indicating that virtualenvwrapper is set up. You now have access to new terminal commands:

  • mkvirtualenv : Make a new virtual environment.
  • workon : Activate/switch to a virtual environment. Remember, you can have as many environments as you’d like.
  • deactivate : Jumps out of a virtual environment and you’ll be working with your system.
  • rmvirtualenv : Deletes a virtual environment.
  • Be sure to read the docs!

Let’s create a Python 3 virtual environment for OpenCV called cv:

And now, using pip, and with a blink of an eye, you can pip install OpenCV on macOS in a matter of seconds into your new environment:

How to pip install OpenCV on Raspberry Pi

Earlier in this post I mentioned that one of the downsides of installing OpenCV is that you don’t have any control over the compile itself — the binaries are prebuilt for you, which while nice, also means you can’t include any additional optimizations.

For the Raspberry Pi, we’re in luck.

Dave Jones (creator of the picamera  Python module) and Ben Nuttall of the Raspberry Pi community-run piwheels.org, a Python package repository providing ARM wheels (i.e., pre-compiled binaries packages) for the Raspberry Pi.

Using PiWheels you’ll be able to pip install OpenCV in a matter of seconds (the same is true for other Python libraries that can take a long time to compile, including NumPy, SciPy, scikit-learn, etc.).

So how do you instruct the pip command to use PiWheels?

The short answer is “Nothing!”

If you’re using Raspbian Stretch you’ll be pleased to know that the pip command will check PiWheels for a pre-compiled binary before it checks PyPI, enabling your Pi to save a bunch of CPU cycles (and you a bunch of install time).

Furthermore, when Ben and Dave put together the OpenCV binary for PiWheels they asked me which instructions they should use — I recommended my optimized OpenCV install for the Raspberry Pi — which is exactly the instructions they followed!

If you end up using pip to install OpenCV on your Raspberry Pi, rest assured, you’re using the optimized version.

Let’s get started learning how to pip install OpenCV on our Raspberry Pi.

Install prerequisites on your Raspberry Pi

The Raspberry Pi requires that you install a few system packages before you get started:

Install pip on your Raspberry Pi

The Python package manager, “pip”, can be obtained via wget:

Now you have two options:

  1. Install OpenCV to your global Python site-packages  on your Raspberry Pi
  2. Install OpenCV into a virtual environment on your Raspberry Pi

Option A: Install OpenCV to your Raspberry Pi system with pip

I wouldn’t recommend this option if you want to be able to use different versions of OpenCV in isolated environments.

But a lot of people deploy their Raspberry Pis for only one purpose/project and don’t need virtual environments.

That being said, it is quite a mess to clean up if you change your mind later and want to use virtual environments, so I’d recommend skipping this option and following Option B.

To pip install OpenCV on your Raspberry Pi system, be sure to use sudo like this::

In a matter of seconds, OpenCV is ready to go in your Raspberry Pi’s site-packages along with any other packages you may have installed.

Option B: Install OpenCV into a virtual environment with pip on your Raspberry Pi

Virtual environments are definitely the way to go if your Raspberry Pi has multiple purposes (or if you’re like me and test code compatibility among various software versions for blog posts all the time ?).

Here’s how to install virtualenv and virtualenvwrapper, the tools I use to get it done:

Then you need to add the following lines to your ~/.bashrc . Open the file using nano , vim , or emacs  and append these lines to the end:

Save the file. Then “source it” in your terminal:

Terminal output will be printed indicating that virtualenvwrapper is ready. Be sure to inspect it for errors.

You now have access to new terminal commands:

  • Create an environment with mkvirtualenv .
  • Activate an environment (or switch to a different one) with workon .
  • Deactivate an environment with deactivate .
  • Remove an environment with rmvirtualenv .
  • Be sure to read the docs!

To create a Python 3 virtual environment which will house OpenCV and other packages you install, simply use mkvirtualenv and the command below:

Now you have a virtual environment named cv . You can activate it any time via:

And now with a flip of the wrist, you can pip install OpenCV into cv :

That’s all there is to it to use PiWheels!

I bet you’re using the PiCamera as your imaging sensor. You can install the Python module using the following command (just take note of the quotes):

Testing our pip install of OpenCV

Did you know that OpenCV’s 3.3+ has a DNN module which can run Deep Learning models?

You might be surprised, but your version of OpenCV can do this out of the box now, with little to no additional software.

We’re going to perform object detection in video with a MobileNet Single Shot Detector.

Here’s what you need to install first (assuming a cv  virtual environment):

Now double check that you have all software ready by opening a Python shell:

The Raspberry Pi will show a different version of Python 3, which is expected.

Now it’s time to download the code.

Be sure to use the “Downloads” section of this blog post to download the source code + pre-trained MobileNet SSD neural network.

From there, execute the following command:

Figure 1: A short clip of Real-time object detection with deep learning and OpenCV

I’m using a Macbook Pro. A framerate of 6 FPS is pretty good using a CPU on a laptop.

Raspberry Pis are resourced constrained, therefore we can leverage a few tricks to create the illusion of higher FPS. If you’re on the Raspberry Pi, execute the following command:

Here I’ve created the illusion of fast 27 FPS on the Raspberry Pi while the neural network in the background is only capable of processing 0.9 FPS.

How is this possible?

Threading and queues.

It’s a little bit advanced, but if you read the original blog post (for the Raspberry Pi), you’ll understand the process. Plus, you’ll be able to impress your friends and family.

What to look out for when using pip to install OpenCV

To start, not all Python distributions will have a version of OpenCV that is pip-installable.

Newer versions of Python and newer operating systems (and not to mention, older versions which have reached their end of life) may not have a version of OpenCV ready to go in the PyPI repository as the open source community has not had a chance to release such a version yet.

In those situations you can either:

  1. Wait until the binaries for your combination of Python and OS are uploaded.
  2. Or what my recommendation would be — compile from source (Ubuntu, macOS, RPi).

Secondly, some readers, including Anaconda users, have reported problems using GUI functions such as cv2.imshow  and cv2.waitKey .

In these scenarios OpenCV will error out saying that it was not compiled with GTK or QT support.

Simply put:

  • You’ll be able to use all other OpenCV functions but you won’t be able to use any of the GUI functions, in particular the ones in the highgui module.
  • The solution here is to compile from source (Ubuntu, macOS, RPi).

Third, I know readers have reported issues when executing import cv2  in their terminals, Jupyter Notebooks, or Python shells — this isn’t an issue with the pip install of OpenCV.

In most, but not all, situations, the error is not related to your actual install of OpenCV.

Instead, it’s more likely a problem with your understanding of some combination of:

  1. The commands that were executed and how to utilize them properly.
  2. Thinking that a command executed correctly but instead resulted in an error.
  3. Failing to access your Python virtual environment (if you are using one).

You’ll want to double-check your commands, repeat the steps, and examine your output closely before reporting an issue importing the cv2  bindings.

Finally, the version of OpenCV that will get installed via pip does not include “non-free” algorithms such as SIFT, SURF, and other patented algorithms. If you don’t need to use patented algorithms, then you’re golden. Otherwise, I recommend that you compile OpenCV from source via one of my installation tutorials for your system.


In today’s tutorial, you learned how to pip install OpenCV on your operating system.

Specifically, we covered how to install OpenCV via pip on Ubuntu, macOS, and Raspberry Pi.

While installing OpenCV via pip may be the easiest method to get you started, keep in mind that you may run into other issues.

If you find yourself running into errors or problems using your pip install of OpenCV, be sure to refer to the “What to look out for when using pip to install OpenCV” section of this blog post.

I hope you enjoyed today’s tutorial!

To be notified when future blog posts are published here on the PyImageSearch blog, be sure to enter your email address in the form below.


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!

, , , , , , ,

122 Responses to pip install opencv

  1. David Hoffman September 19, 2018 at 11:15 am #

    This method with pip has come a long way — it is an easy way to get started with OpenCV and lowers the barrier to entry for many folks. Thanks for sharing Adrian!

    • kaisar khatak October 14, 2018 at 6:24 pm #

      Will “pip install opencv-contrib-python==3.4.3” leverage the GPU or is it CPU only functionality??? If we want OpenCV to use the GPU, must we compile OpenCV from source???

      Ubuntu 16 (AWS P2 instance)


      • Adrian Rosebrock October 16, 2018 at 8:38 am #

        It will likely only use your CPU. For any type of optimizations or GPU support I would highly encourage you to compile from source.

  2. Dany September 19, 2018 at 11:20 am #

    Thank you Adrian. It’s possible install two version of OpenCv in two separated enviroment?

    • David Hoffman September 19, 2018 at 9:05 pm #

      Hi Dany. Yes. Try this:

  3. Max Lee September 19, 2018 at 12:41 pm #

    I noticed these extra packages show up in the repository a few days ago and thought I was just mistaken… I’m so glad to see that they are real, and that they are from you.

    Thank you so much, congrats on your marriage, and take care!

  4. wally September 19, 2018 at 12:53 pm #

    This is awesome news! About your honeymoon and openCV!
    Hopefully openCV 4 will be built soon after its release.

    I expect I will try it soon on a PiZero-W with Movidius.

    I know you recommended a minimal openCV installed for NCS but I have been using the NCS with OpenCV 3.4.2 compiled on Ubuntu 16.04 by building the NCS sdk with the old repo version of openCV, and then creating a python virtual environment and compiling ocv 3.4.2. I then got the ncs api to work by simply copying the mvnc python module to my virtual environment.

    It seems to work as I’ve pulled together several of your tutorials into a single python script that will use the ncs if one is plugged in and fall back to using the cpu only dnn module if no ncs devices are found or its running on Windows (limited testing so far). I can select using multiple onvif netcameras (my preferred solution now since round robin sampling of multiple cameras is trivial), the picamera module, or a USB webcam.

    For performance, pretty much need the ncs on a Pi, on an i7 cpu dnn module is significantly faster. On an i3 (windows) the Pi with ncs is about the same as the cpu only dnn. My speed conclusions could be in error if the pre-compiled windows openCV is using gpu acceleration with the opencv-contrib-python version.

    • David Hoffman September 19, 2018 at 9:00 pm #

      Hi Wally, thanks for sharing about your experience with Movidius. As far as the Pi Zero W, I haven’t tried to pip install OpenCV on it yet — I think it will work, but I’m not sure. On the Pi Zero W, I’ve only had luck with Raspbian Jesse. I couldn’t compile OpenCV on Stretch despite multiple attempts. I haven’t used Onif Netcameras — thanks for sharing about it.

  5. Jerome September 19, 2018 at 1:10 pm #

    Once upon a time, pip 🙂
    great news
    thanks for sharing Adrian !

  6. fred September 19, 2018 at 2:26 pm #

    Will save me much time to compile the source code, thank you Adrian.

  7. Bojan Matovski September 19, 2018 at 3:49 pm #

    Sorry if I missed it, but I didn’t saw any comments as to what’s the difference between opencv-python and opencv-contrib-python.

    I’m looking forward to this pip based install, but I’m just having a feeling that something will not work as intended. Maybe when it will be officially accepted by opencv.org I will change my mind, but up till then I will just stick to the old fashioned way (unless I need to do it fast on some machine).

    I mean, I’ve done it so many times and on so many machines (mostly thanks to you and your tutorials of course) that I really feel very comfortable installing it from scratch.

    Anyway, all the best and cheers for the new tutorial!

    • Abhishek Thanki September 20, 2018 at 8:44 am #

      Hi Bojan,

      The difference is that opencv-contrib-python includes modules in the contrib repository as well. The contrib repository contains algorithms such as SIFT, SURF, and others. In the past, these implementations were included in the default installation; however, they were moved beginning with OpenCV 3+.

      Modules that are actively being developed and/or modules that are patented (not free for commercial/industry use) are included in the contrib module. For example, SIFT and SURF fall into this category.

      I can assure you that except for the issues mentioned in blog post with Anaconda, it works just as fine as compiling from the source. 😉

  8. Ibn Ahmad September 19, 2018 at 4:50 pm #

    Thanks for this tutorial. It came really handy as I have spent lots of hours running into days trying to install OpenCV despite following your tutorial in some of your other article.

  9. xema September 20, 2018 at 3:18 am #

    Thanks for this tutorial, but I have a segmentation fault when I want show an image with

    cv2.imshow('Output', output)

    QObject::moveToThread: Current thread (0x4ece310) is not the object's thread (0xc95b190).
    Cannot move to target thread (0x4ece310)

    The same with imwrite. Other functions work fine.

    print (cv2.__version__) returns 3.4.3. I am using python 3.5 with virtualenvwrapper.

  10. Mark C September 20, 2018 at 3:39 am #

    Why Not on Windows?

    • Abhishek Thanki September 20, 2018 at 9:28 am #

      Hi Mark,

      I tried pip3 install opencv-contrib-python on a friend’s laptop (windows 10) and it worked! Just make sure you do it using virtualenv and virtualenvwrapperto be on the safe side.

      • Newb September 21, 2018 at 1:43 am #

        What do you mean by “to be on the safe side”?

  11. Bajjee September 20, 2018 at 5:45 am #

    I am getting following error in my RaspberryPI.
    Traceback (most recent call last):
    File "pi_object_detection.py", line 84, in
    frame = imutils.resize(frame, width=400)
    File "/home/pi/.virtualenvs/cv/lib/python3.5/site-packages/imutils/convenience.py", line 69, in resize
    (h, w) = image.shape[:2]
    AttributeError: 'NoneType' object has no attribute 'shape'

    • David Hoffman September 20, 2018 at 8:39 am #

      Hi Bajjee, see this blog post about resolving NoneType errors.

      • Bajjee September 21, 2018 at 12:59 am #

        I found a typo in line #74. Line 74 should be commented out and line 75 should be uncommented for RaspberryPI, once i did that, code worked as expected.

        Thank you, works great.

    • Andrew August 1, 2019 at 4:54 pm #

      I got this error too. I have a multiple monitor setup on my mac. It seems to mess with the camera built into my laptop – even photobooth/facetime can’t seem to get the camera working and when I run the python script I get that error. It just can’t find the camera. If I shutdown (not restart) and start up again without the other monitors connected it works.

  12. marco September 20, 2018 at 8:00 am #

    Hello, I’m trying to follow this apparently beautiful installation on my Raspberri but I stopped immediately because launching the command “pip install virtualenv virtualenvwrapper” at the end I get the following red error “Could not install packages due to an EnvironmentError: [ Errno 13] Permission denied: ‘/usr/local/lib/python3.5/dist-packages/virtualenv.py’
    Consider using the --user option or check the permissions” How can I resolve this permissions problem?

    thank you

    • David Hoffman September 20, 2018 at 8:34 am #

      Hi Marco, it sounds like you’re trying to install the tools into a system folder or maybe something isn’t configured correctly. If you use the –user switch, it should resolve the issue. Try this: pip install --user virtualenv virtualenvwrapper

      • marco September 20, 2018 at 2:42 pm #

        hi David, thanks for the answer, I tried the line that you hi suggested and apparently seems to be successful in fact basically says:
        Successfully installed pbr-4.2.0 stevedore-1.29.0 virtualenv-16.0.0 virtualenv-clone-0.3.0 virtualenvwrapper-4.8.2

        but then launching the command:
        source ~/.profile
        bash: /usr/local/bin/virtualenvwrapper.sh: File or directory does not exist
        from the error above

      • marco September 20, 2018 at 2:48 pm #

        I forgot, before: successfully installed virtualenv …. in orange there are also these lines:
        The script is virtualenv installed in ‘/home/pi/.local/bin’ which is not on PATH.
        Consider adding this directory to PATH or, if you prefer to suppress this warning, use –no-warn-script-location.

    • Denis Brion September 21, 2018 at 6:36 am #

      worked with sudo pip install ….

  13. Prasanth September 20, 2018 at 8:16 am #

    Hi Adrian,

    i tried to compile Open CV on windows 10 using visual studio 2015, able to perform CMake steps but unable to compile project in Visual Studio. Any idea how to resolve ?

  14. Denis Brion September 21, 2018 at 6:34 am #

    This is a huge improvements to source compiling for RPi users:
    there remain some little details
    a) with pip, dependencies such as jasper ane catlas should be already installed via apt-get (I detected I needed libjasper.so; I apt-got its dev counterpart)
    b) your demo program assumes there is a video camera connected and working on the RPi. For self teaching, people may try first with already existing videos….

  15. David Killen September 21, 2018 at 11:22 am #

    Thank you for providing this.

    It’s a trivial point to many people here, but it took me a little while to diagnose.
    I received the error

    [INFO] loading model…
    [INFO] starting video stream…
    Traceback (most recent call last):
    File “real_time_object_detection.py”, line 49, in
    frame = imutils.resize(frame, width=400)
    File “/home/david/.local/lib/python3.6/site-packages/imutils/convenience.py”, line 69, in resize
    (h, w) = image.shape[:2]
    AttributeError: ‘NoneType’ object has no attribute ‘shape’

    It was, of course, because there is no webcam on my laptop. Once I had amended

    vs = VideoStream(src=0).start() # (line 3 in file real_time_object_detection.py)

    to point to an mp4 video-file everything worked fine.

  16. Dennis September 22, 2018 at 11:16 am #

    “…Secondly, some readers, including Anaconda users, have reported problems using GUI functions such as cv2.imshow and cv2.waitKey .”

    I use OpenCV on both RPi and Anaconda on my PC. Don’t use PIP to install OpenCV use the conda command:

    conda install -c conda-forge opencv


    • aarju October 16, 2018 at 7:35 am #

      after installing cv2 using this(downloaded by above link) command,no error is coming,but this line cap = cv2.VideoCapture(0) returns false.

      • Adrian Rosebrock October 16, 2018 at 8:11 am #

        Make sure you have your webcam properly installed and working. What type of camera are you using?

  17. loch September 22, 2018 at 9:38 pm #

    HI adrian

    your code work perfectly , earlier i had opencv 3.2.0 where camera release function perfectly
    but after upgrading to opencv 3.4.2 to run the programme the camera release( capture.release() ) function not working can u give me a solution to release the camera thank you

  18. Antonio September 24, 2018 at 10:43 am #

    Hey Adrian,

    if I install it via pip on Rasberry Pi, will it included NEON optimizations?
    If I install it on my desktop machine, will it include OpenCL support?

  19. suresh September 26, 2018 at 1:36 am #

    Hi i’m trying to “pip install opencv-contrib-python” in raspberry pi srtetch os. While installing i’m getting “Could not find a version that satisfies the requirement opencv-contrib-python (from versions: )No matching distribution found for opencv-contrib-python..” Please help me with the error.

    • David Hoffman September 26, 2018 at 12:38 pm #

      Hi Suresh, which hardware (Pi 3B, Pi 3B+, etc.) are you using?

      • hutu September 30, 2018 at 3:54 am #

        Hi David,

        I solved this issue by Ben’s FAQ in github: adding the piwheels index to /etc/pip.conf.

        as i’m guessing piwheels is by default missing inside stretch lite.

        add below lines to /etc/pip.conf :

        • John November 23, 2018 at 2:08 pm #

          Thanks hutu!
          This was exactly the solution.

        • Pedro June 9, 2019 at 8:56 pm #

          This was exactly my solution to error ERROR: Could not find a version that satisfies the requirement opencv-contrib-python (from versions: none)
          ERROR: No matching distribution found for opencv-contrib-python on Raspi Zero W

          File /etc/pip.conf doesent exists, I create it and put his code and after this I can install

          • srujan June 12, 2019 at 6:08 pm #

            Hey Pedro,

            I am using a headless Raspbian stretch. I am facing this error and couldn’t find the etc/pip.conf. Could you help me with the instructions on how to create this file? Thanks

      • Tomas Cechura October 10, 2018 at 3:58 am #

        Hi, I experienced the same behaviour on my RPi 3B+ with latest Raspbian Stretch Lite – any suggestions?

        • Kevin October 28, 2018 at 4:39 am #

          I had this problem as well on the RPi 3B+ and I found out that my pip version was just too outdated. Try running

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

          even if you already have pip installed that should get it up to date.

  20. Adrian September 26, 2018 at 7:29 am #

    Hi! Adrian, in the first place i have installed opencv 3.4.1 with all features like “Gstreamer” already and after to update with “pip install” comand to opencv 3.4.3 all thats features was disable….

    you know how to set this settings again like “-with Gstreamer=ON” or something?

    • Antoni October 6, 2018 at 4:16 am #

      I’m having exactly the same error tha Suresh. Trying to install in Raspbian strech in 3B+ with Python 3.7.

      • Adrian Rosebrock October 8, 2018 at 9:46 am #

        Which Raspberry Pi hardware are you using? Can you confirm your exact Raspbian Stretch version as well? I would suggest trying on a fresh install of Raspbian to see if that resolves the issue.

        • Antonio Bardaji Cuso October 13, 2018 at 5:55 am #

          Hi Adrian,

          I’m using latest version of Raspberry Pi 3B+ with latest version of Raspbian Stretch 9.4. with python 3.7.
          Trying to install Opencv using pip. I got the same message than Suresh: “Could not find a version that satisfies the requirement opencv-contrib-python (from versions: )No matching distribution found for opencv-contrib-python..”

          Any Idea?

          • Adrian Rosebrock October 16, 2018 at 8:48 am #

            See my reply to Simeon.

          • pite May 18, 2019 at 6:04 am #

            try using pip3

    • Adrian Rosebrock October 8, 2018 at 9:46 am #

      If you’re trying to customize the install you should compile and install OpenCV from source.

  21. hutu September 30, 2018 at 5:27 am #

    Hi Adrian,

    the tutorial is not working for stretch lite which is popular for headless use of rpi3 b/b+. still need a lot walk-around. whether you can check also as it’s quite advanced topics for new comer.


    • hutu September 30, 2018 at 6:00 am #

      Hi Adrian,

      I’m wrong, stretch lite for vision related application is useless as without gui/display output to show result 🙁

      sorry I’m new to this area…

      • Adrian Rosebrock October 8, 2018 at 12:06 pm #

        Stretch Lite doesn’t have a window manager which is why you don’t see any output images. You would need to install a window manager and/or install X11 and then SSH into your Pi with X11 forwarding enabled.

  22. Ulises Flynn October 3, 2018 at 3:36 pm #

    After installing virtualenv in osx:

    $ which virtualenvwrapper.sh

    $sudo ln /Library/Frameworks/Python.framework/Versions/3.6/bin/virtualenvwrapper.sh /usr/local/bin/virtualenvwrapper.sh

    This fixes the virtualenvwrapper.sh not being found in the .bash_profile.

  23. Nigel October 9, 2018 at 12:40 pm #

    As usual a well written article and highly useful article.
    I see that virtualenv is being used. But python offers a virtual environment venv. Can one use this or should one stick to virtualenv?

    • Adrian Rosebrock October 12, 2018 at 9:29 am #

      I personally prefer virtualenv and virtualenvwrapper together but it’s your personal preference.

  24. Dennis Mabrey October 12, 2018 at 6:06 pm #

    On the Raspberry PI I kept receiving errors when I would import cv2 in python3.
    It would say: ImportError: libcblas.so.3: cannot open shared object file: No such file or directory

    I did find the fix for it here: https://github.com/amymcgovern/pyparrot/issues/34#issuecomment-379557137

    I had to install these dependencies:

    sudo apt-get install libatlas-base-dev
    sudo apt-get install libjasper-dev
    sudo apt-get install libqtgui4
    sudo apt-get install python3-pyqt5

    • Adrian Rosebrock October 16, 2018 at 8:49 am #

      Thanks for sharing Dennis!

    • cbasavaraj October 26, 2018 at 2:41 pm #

      Hi, I installed all the above dependencies. Yet I now get ImportError: libImath-2_2.so.12
      But to be noted that I am using Stretch Lite and did pip install opencv-python-headless

      • Brian H Wilson November 19, 2018 at 9:52 pm #

        I am having the same problem. Same set up. Stretch Lite

        Using python3 in a virtualenv

        Did not make any difference, headless or not, contrib or not, same thing.

        • Avery Uslaner February 2, 2019 at 9:55 pm #

          When you run into issues like these, it’s helpful to search your package manager using the command:

          $ sudo apt-cache search packagename

          So in this case, you would find that you need to do:

          $ sudo apt-get install libilmbase12

    • Santiago February 13, 2019 at 9:57 am #

      Thanks for sharing friend! it works for me.

    • Harsh May 12, 2019 at 6:40 pm #

      Other than above dependencies, I have installed ffmpeg to fix importerror: libswscale.so.4

      sudo apt-get install ffmpeg

  25. Simeon October 13, 2018 at 8:01 am #

    Hi Adrian. I’m getting an error saying no matching distribution found for opencv-contrib-python. Trying to installl it on the raspberry pi with Ubuntu LX OS. Does this mean I need to install from source?

    • Adrian Rosebrock October 16, 2018 at 8:47 am #

      Yes, if there is no matching distribution then there are no pre-compiled versions of OpenCV you can install via pip. You would need to compile OpenCV from source. Be sure to refer to my OpenCV install tutorials to help you get started.

      • pite May 18, 2019 at 6:03 am #

        pip gave me that error but pip3 worked

  26. Angenieux October 22, 2018 at 3:03 pm #

    Dear All,
    I’m trying to “pip install opencv-contrib-python” on a RASPBERRY PI ZERO W (RASPBIAN STRETCH WITH DESKTOP).

    I have the following issue ” Could not find a version that satisfies the requirement opencv-contrib-python (from versions: ) No matching distribution found for opencv-contrib-python

    Any help is welcome.
    Last time I compiled opencv on raspberry pi it took to long time. 😉

    Thanks a lot

    • Adrian Rosebrock October 29, 2018 at 2:17 pm #

      It unfortunately means there are no pre-compiled versions available for your Raspberry Pi Zero. You will need to compile and install OpenCV from source.

  27. RD October 31, 2018 at 10:17 am #

    I tried the tutorial but had a problem in the first go. I was not able to install pip.
    I installed using the sudo apt command

    $ sudo apt install python3-pip

    This installed pip for me. But I realized that the pip was installed for python3 and not for python 2. That means I had to use pip3 instead of pip to install opencv.
    The following code (as mentioned in the tutorial) did not work for me
    $ sudo pip install opencv-contrib-python

    But when I use pip3 instead of pip then the installation runs fine.
    $ sudo pip3 install opencv-contrib-python

    Is this something that has only happened for me or has someone else also faced the same problem. Form what I read online, pip3 is for python3 and pip is for python2

  28. Jafet Mora November 8, 2018 at 1:10 am #

    Hello, I installed opencv in my RPi Zero (Raspbian Stretch) by means of pip, my current version is 3.4.3. and when trying to compile the “pi_object_detection.py” code located in the download area, with python and python3 after the program shows “[INFO] loading model …”
    “[INFO] starting process …”
    “[INFO] starting video stream …”
    show this:
    Illegal instruction

    I do not know if it should be a problem with the opencv installed from piwheels, or if it is something in the code that needs to be changed, and if not, could anyone help me install version 3.3+ in the RPi Zero from the source ?

    • Adrian Rosebrock November 10, 2018 at 10:11 am #

      Can you insert a few “print” statements to debug exactly which line is causing execution to stop? I’m willing to bet it’s “imutils.resize”. For some reason the Pi Zero doesn’t like the inter flag set to cv2.INTER_AREA. If you change it to cv2.INTER_LINEAR it should work.

  29. Kevinl7778 November 19, 2018 at 4:19 pm #

    The pip install went smooth, but I cant find the data folder containing the haarcascade clasifier and other stuff.

    Any idead as to where it would be on the raspbian pixel?

    • Adrian Rosebrock November 20, 2018 at 9:22 am #

      The pip install of OpenCV is a pre-compiled binary. It does not contain the additional directories from a clone of the GitHub repo. You can find what you’re looking for in OpenCV’s GitHub.

  30. KEVINL7778 November 21, 2018 at 7:48 pm #

    I found them here: (PIP3 install)


    I will testit out tonight.

    Thanks for all of the work you list on the site and good luck with the sale.


    • Adrian Rosebrock November 25, 2018 at 9:37 am #

      Thanks Kevin!

  31. John November 22, 2018 at 3:45 pm #

    Virtual wrapper is also missing a distribution. Worthless advice here. Method doesn’t work.

    • Adrian Rosebrock November 25, 2018 at 9:21 am #

      Hey John — that actually sounds like a problem with your local dev environment and potentially even a network issue. Without knowing more about your dev environment neither myself nor anyone can help you. If you are going to take the time to write a comment on my blog I would also suggest you take the time to describe your environment and any error you are getting, otherwise I’m afraid we are both wasting our time which is something I do not want 🙁

  32. Colin December 13, 2018 at 9:05 am #

    My robot Raspberry Pi brain has all of its code written in Python 2.7 and it would be a major task to rewrite in Python 3. Does this pip installation work for 2.7? If so I would be grateful for pointers as to what to change.

    • Adrian Rosebrock December 13, 2018 at 9:15 am #

      It should although I no longer support Python 2.7 officially here on PyImageSearch. You would just want to create a Python 2.7 virtual environment instead of a Python 3 one:

      All steps should be the same.

  33. Heiko Zschimmer December 17, 2018 at 3:23 pm #

    Is there a way to select picam?
    it seems that the default settings use a USB cam?

    • Adrian Rosebrock December 18, 2018 at 8:56 am #

      I would instead suggest you use my VideoStream class which works with both USB cameras and the Raspberry Pi camera module.

  34. hotdog January 1, 2019 at 3:07 am #

    i want to know why i always install the opencv in the python2 not in the python3, thanking you!

    • Adrian Rosebrock January 2, 2019 at 9:12 am #

      Are you using Python virtual environments? Which version of Python are you trying to install OpenCV for?

  35. Hasan January 2, 2019 at 12:38 pm #

    Hi Dr.Adrian,
    I am new with OpenCV and I am using Win 10.
    So, please
    How I can install opencv-contrib-python and continue with Opencv course.

  36. Yilliang Peng January 6, 2019 at 9:38 pm #

    Hi Adrian! I just wanna ask you if there is any difference with “make -j4” and “pip install opencv-contrib-python” because I installed it first with make -j4 and it cause and error while with pip it works perfectly. Is it going to be fine?

    • Adrian Rosebrock January 8, 2019 at 6:57 am #

      Keep in mind that the opencv-contrib-python module is NOT the same as compiling and installing from scratch. If you install via pip you will not have the NONFREE modules from the contrib package (such as SIFT and SURF).

      If you run into any errors related to the NONFREE modules when executing your code you will know it’s because of the pip install (and then you’ll need to compile OpenCV from source).

  37. Hasan January 7, 2019 at 3:57 pm #

    Does n’t matter Dr., I think that I get the solution. Thanks

    • Adrian Rosebrock January 8, 2019 at 6:45 am #

      Congrats on getting OpenCV installed, Hasan!

  38. Sam T January 26, 2019 at 12:49 pm #

    HI , this is the third time i am compiling. I dont know why the root folder is using all the available space of the sd card 16gb

    and the compilations stops with a fatal error that there is no space.

    Please help me out.

    • Adrian Rosebrock January 29, 2019 at 6:51 am #

      Just to clarify, are you compiling OpenCV from source? Or are you installing OpenCV via pip? Installing OpenCV via pip shouldn’t use up much disk space so I get the impression that you’re compiling from source — but you’re commenting on a pip install post. Could you clarify?

  39. Yaya February 20, 2019 at 6:12 am #


    I got this error when import cv2 module

    “ImportError: numpy.core.multiarrayfailed to import”
    How can I fix it?


    • Adrian Rosebrock February 20, 2019 at 12:00 pm #

      It sounds like you haven’t installed NumPy yet:

  40. Shymaa Abo Arkoub February 28, 2019 at 1:07 pm #

    can not we install it on window?

    • Adrian Rosebrock February 28, 2019 at 1:27 pm #

      You can install OpenCV Windows but I do not officially support Windows here on the PyImageSearch blog. If you are interested in computer vision and OpenCV I highly suggest you use a Unix-based OS such as Ubuntu or macOS.

  41. Ebi April 1, 2019 at 3:58 pm #

    Hey, I have installed opencv2 on my windows (in cmd when I go to python and import cv2, there is no error), but how in my project doesn’t know it? I have to install it by “pip install opencv-python”. I can not install it globally?

    • Adrian Rosebrock April 2, 2019 at 5:46 am #

      Are you using Python virtual environments? If so, I advise installing OpenCV into the virtual env (not globally).

  42. Brad April 8, 2019 at 6:39 am #

    Thanks for a super useful resource Adrian!

    I’m trying to understand why images are being resized to 300 x 300 in pi_object_detection.py. I was under the impression that MobileNet expects images of 224 x224? What am I missing?

    Also, would it not be more performant to set image width and height on the original video stream, rather than resizing each frame for the detection process?

    • Adrian Rosebrock April 12, 2019 at 12:36 pm #

      Actually, the MobileNet SSD trained on the COCO dataset accepts 300×300 inputs, not 224×224 ones. You could also set the dimensions via the video stream as well.

  43. Zubair Ahmed April 8, 2019 at 7:39 am #

    Hi Adrian

    Thanks for writing this, I just followed it to install OpenCV on my new Raspberry Pi 3B+

    Looks like you need to also install sudo apt-get install libjasper-dev

    Without this I was getting an import error ‘libjasper.so.1: cannot open shared object file: No such file or directory’

  44. Chip Williams April 11, 2019 at 8:54 pm #

    install of opencv-contrib-python with pip on RPi 3B+ did not work.
    – Running Raspbian Stretch clean install
    – Have installed virtual environments and that seems to be working fine
    – The installation procedure completed successfully
    – I did a workon cv to get into the virtual environment
    – A help() modules shows that cv2 is present
    – import cv2 results in error message:
    “ImportError: libcblas.so.3: cannot open shared object file: No such file or directory”

    Where was that library supposed to come from? Thanks.

    • Chip Williams April 12, 2019 at 9:10 am #

      OK. So had to apt-get install libatlas3-base and then libjasper1.

  45. Chip Williams April 12, 2019 at 9:18 am #

    So having worked through this process I can now run the demo on the RPi 3B+ but my output does not look like what Adrian posted above. My frame is larger vertically than the image and if I run my mouse over the top of the image the image coordinate and the RGB value are displayed at the bottom of the frame about a third truncated. Then there is also a dead space between the top of the image and the bottom of the title bar. If I click in that dead space it zooms in and displays the RGB value on every pixel. This action is inconsistent with what cv2.imshow() has done on other platforms. Anybody have an idea what entity has added all this (unwanted) extra functionality? How do you get rid of it?

    • Adrian Rosebrock April 12, 2019 at 11:15 am #

      This seems like a GUI-related issue with the pre-built OpenCV binary. What version of OpenCV was installed?

  46. Akshay Chaturvedi May 3, 2019 at 5:36 am #

    Hi Adrian,
    Great Article and big fan. I am having this very weird problem. After successful installation on every package and doing every step properly. I just ran a file(python file.py) with command cv2.imread(‘Download.jpg’) and it says AttributeError :module ‘cv2’ has no attribute ‘imread’

    Also after rebooting the Pi and running the python shell and import cv2 gives the same error.

    I am really looking for some help desperately.

    • Adrian Rosebrock May 8, 2019 at 1:37 pm #

      That is incredibly, incredibly strange. What OS were you tryin to install OpenCV on?

  47. kilari Parthasarathy May 14, 2019 at 3:10 am #

    Hi, I was reading this article and knew how install opencv using pip in different operating systems. can we install the same in windows.

    • Adrian Rosebrock May 15, 2019 at 2:41 pm #

      Potentially, but I’m not sure. I do not support Windows here on the PyImageSearch blog (see the FAQ).

  48. vindo July 2, 2019 at 4:24 am #

    hey i already followed your tutorial and when i tried to import cv2 in terminal it said no module named cv2

    • Adrian Rosebrock July 4, 2019 at 10:23 am #

      Make sure you use the “workon” command to access your Python virtual environment first.

  49. David Joseph T July 9, 2019 at 7:25 pm #

    A tutorial on how to install OpenCV on windows machine would have been great to, cos i use a windows pc, thanks

    • Adrian Rosebrock July 10, 2019 at 9:34 am #

      Sorry, I don’t cover Windows nor support Windows here on the PyImageSearch blog for reasons discussed in the FAQ.

  50. dan b July 13, 2019 at 5:34 pm #

    Having the problem referred to above where PIP cannot fine version of opencv-contrib-python.

    I have raspi v10 (buster)

    I have tried the two potential solutions described above, editing the /etc/pip.conf file to replace the existing entry (ending the line w … hostedpi.com/simple

    And also tried the PIP3 variant suggested with the same error resulting.

    Please help. Trying to compile opencv has failed with various errors in libraries/cmake/make etc, so compiling is not an option. Is this an issue with raspi 10?

    • dan b July 13, 2019 at 11:57 pm #

      Cancel that request. The problem was indeed the version switch for raspian (version 10 does not work; version 9 works fine.

      Note that the raspian NOOBS main page does a poor job explaining which version of raspian you actually get when you click on the download button. Now that version 10 is the default, maybe you could add a line in your tutorial telling people to check the version of raspian. A simple $ cat /etc/os-release at the terminal prompt would have saved me a few hours of frustration.

      Thanks for all the fine work you do for the opencv community.

      • Adrian Rosebrock July 25, 2019 at 10:07 am #

        Thanks Dan. Just to add an additional comment — I don’t recommend using NOOBS. Use the standard Raspbian install.

      • BBC_Basic August 21, 2019 at 2:45 pm #

        HI Dan,
        I am new to Raspberry Pi and don’t know where to find the switch that you refer too. I ran $ cat /etc/os-release and find that i am running version 10.

        Can I change this or is it a reinstall?

  51. A.B August 24, 2019 at 8:36 pm #

    I actually spoke too soon but was able to recover from another install issue for opencv, this time related to numpy.

    If it complains about the version of numpy it wants to install is not valid for python 3.4.4 (see previous post), you can check which version is appropriate for 3.4.4 from https://www.piwheels.hostedpi.com/simple/numpy/.

    Since numpy 1.16.4 is the appropriate version for python 3.4.4, you can install it via

    pip3 install numpy==1.16.4 -vvv

    Then redoing the command pip3 install opencv-contrib-python (which again is going to install the version appropriate for the tags listed by the pip debug command) should be successful.

  52. Daniel Ferguson September 7, 2019 at 12:14 am #

    Thanks so much for this info, and for your articles in general.

    If I use this installation method, can I cmake third-party libraries (e.g. BackgroundSubtractorCNT) that reverence OpenCV? It seems this method does not create any OpenCV environment variables and does not have an OpenCVConfig.cmake file.

    • Adrian Rosebrock September 12, 2019 at 12:00 pm #

      Unfortunately you will need to compile OpenCV from source.

  53. Jon H September 7, 2019 at 9:04 pm #

    Thank you Adrian!

    It’s working on Raspbian Buster on a Pi 4, but to close out I x out of terminal and to run it again I have to start from

    source ~/.profile
    mkvirtualenv cv -p python3
    workon cv

    What is the right way to end so it doesn’t wipe my virtualenv?

    • Adrian Rosebrock September 12, 2019 at 11:59 am #

      You can add those commands to your “.profile” or “.bashrc” file so they are automatically loaded each time you own a new terminal.

Before you leave a comment...

Hey, Adrian here, author of the PyImageSearch blog. I'd love to hear from you, but before you submit a comment, please follow these guidelines:

  1. If you have a question, read the comments first. You should also search this page (i.e., ctrl + f) for keywords related to your question. It's likely that I have already addressed your question in the comments.
  2. If you are copying and pasting code/terminal output, please don't. Reviewing another programmers’ code is a very time consuming and tedious task, and due to the volume of emails and contact requests I receive, I simply cannot do it.
  3. Be respectful of the space. I put a lot of my own personal time into creating these free weekly tutorials. On average, each tutorial takes me 15-20 hours to put together. I love offering these guides to you and I take pride in the content I create. Therefore, I will not approve comments that include large code blocks/terminal output as it destroys the formatting of the page. Kindly be respectful of this space.
  4. Be patient. I receive 200+ comments and emails per day. Due to spam, and my desire to personally answer as many questions as I can, I hand moderate all new comments (typically once per week). I try to answer as many questions as I can, but I'm only one person. Please don't be offended if I cannot get to your question
  5. Do you need priority support? Consider purchasing one of my books and courses. I place customer questions and emails in a separate, special priority queue and answer them first. If you are a customer of mine you will receive a guaranteed response from me. If there's any time left over, I focus on the community at large and attempt to answer as many of those questions as I possibly can.

Thank you for keeping these guidelines in mind before submitting your comment.

Leave a Reply