Checking your OpenCV version using Python


It was unavoidable — the OpenCV 3 release was bound to break backwards compatibility with some OpenCV 2.4.X functions: cv2.findContours  and cv2.normalize  come to mind right off the top of my head.

So how do you ensure that your code will work no matter which version of OpenCV your production environment is using?

Well, the short answer is that you’ll need to create if  statements around each of the offending functions (or abstract the functions away to a separate method that handles calling the appropriate function based on your OpenCV version).

In order to do this, you’ll need to be able to check your OpenCV version from within your using Python — and that’s exactly what the rest of this blog will show you how to do!

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

Checking your OpenCV version using Python

The OpenCV version is contained within a special cv2.__version__  variable, which you can access like this:

The cv2.__version__  variable is simply a string which you can split into the major and minor versions:

Of course, having to perform this operation every time you need to check your OpenCV version is a bit of pain. To resolve this problem, I have added three new functions to my imutils package, a series of convenience functions to make basic image processing functions with OpenCV and Python easier.

You can see my is_cv2 , is_cv3 , and check_opencv_version  functions below:

The code here is fairly straightforward — I’m simply checking if the cv2.__version__  string starts with a 2 , indicating we are using OpenCV 2.X, a 3 , to indicate that we are using OpenCV 3, or a 4 , to indicate that we are using OpenCV 4.

Again, these functions have already been included in the imutils package, which you can install using pip:

If you already have imutils  installed, you can upgrade to the latest version using:

Checking your OpenCV version: a real-world example

Now that we know how to check our OpenCV version using Python as well as defined a couple convenience functions to make the version check easier, let’s see how we can use these functions in a real-world example.

Our goal here is to detect contours in the following image:

Figure 1: We are going to utilize OpenCV 2.4.X and OpenCV 3 to detect the contours of the Tetris blocks.

Figure 1: We are going to utilize OpenCV 2.4.X and OpenCV 3 to detect the contours (i.e. outlines) of the Tetris blocks.

In order to detect contours in an image, we’ll need to use the cv2.findContours  function. However, as we know, the return signature of cv2.findContours  has changed slightly between version 3 and 2.4 of OpenCV (the OpenCV 3 version of cv2.findContours  returns an extra value in the tuple) — thus we’ll need to perform a check to our OpenCV version prior to making a call to cv2.findContours  to ensure our script does not error out. Let’s take a look at how we can make this check:

As you can see, all we need to do is make a call to is_cv2  , is_cv4 , and is_cv3  and then wrap our version specific code inside the if  statement blocks — that’s it!

Now when I go to execute my script using OpenCV 2.4, it works without a problem:

Figure 2: Our call to cv2.findContours is working in OpenCV 2.4.X.

Figure 2: Our call to cv2.findContours is working in OpenCV 2.4.X.

And the same is true for OpenCV 3:

Figure 3: And the same is true for OpenCV 3 since we are using the is_cv2 and is_cv3 functions to detect OpenCV versions with Python.

Figure 3: And the same is true for OpenCV 3 since we are using the is_cv2 and is_cv3 functions to detect OpenCV versions with Python.


In this blog post we learned how to check our OpenCV version using Python. The OpenCV version is included in a special string variable named cv2.__version__ . All we need to do is check this variable and we’ll be able to determine our OpenCV version.

Finally, I have defined a few convenience methods inside the imutils package to make checking your OpenCV version easier and more Pythonic. Consider checking the library out if you find yourself needing to consistently check OpenCV versions.


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!

, , ,

22 Responses to Checking your OpenCV version using Python

  1. Michel October 5, 2015 at 11:10 am #

    Thanks for the tutorial, Adrian.

    Unfortunately, imutils is no avail for windows. How could it be solved?

    • Adrian Rosebrock October 5, 2015 at 7:06 pm #

      You can install it via pip:

      pip install imutils

      • Michel October 5, 2015 at 9:06 pm #

        Yes, Adrian!
        It works again. Thanks!

  2. Brian February 10, 2016 at 11:06 am #

    Hi Adrian. Get tutorials.
    I’m attempting a project using a RasPi which sorts small building blocks by size and colour. Firstly, its looking for cube blocks of a certain size – anything too small/large/long etc it ignores and secondly, if the correct size, it determines the block colour. Its looking for red, blue and yellow.
    Could I use the code type above to detect block size? I’m thinking threshold (background will be white) and get object area in pixels. Compare this to area of ‘ideal’ block?
    I tried previously using object detection with a template image of an ‘ideal’ block but the Pi seemed quite slow at this and the camera focus isn’t great at close distances.
    I’d love to hear your thoughts! Thanks

    • Adrian Rosebrock February 10, 2016 at 4:31 pm #

      Hey Brian, if you’re looking to compute the size of the block, use the cv2.contourArea function. You can see an example of computing the contour area in this post.

      • Yash Jain January 11, 2017 at 9:53 am #

        Hey Adrian,
        I am using opencv 3.1.0 but the repo on github to which I want to contribute to uses ‘import cv’ statement to use it so which OpenCV version should I install to use it.
        I know it is a silly question but it is very important to get the answer.

        • Adrian Rosebrock January 11, 2017 at 10:29 am #

          If you want access to the old “cv” bindings you should either (1) use OpenCV 2.4 where you an access them via* or (2) you can compile OpenCV 3 with the previous bindings enabled. I’m not sure what the configuration switch to CMake is to do that. I would suggest running ccmake .. (note the two “c’s” in the command and then enabling any option related to “opencv world”.

  3. Andrew June 15, 2016 at 5:19 am #

    For OpenCV versions prior to 2.4.0 the cv2.__versions__ string looks like “$Rev: 1234 $” so your split example will fail and your is_cv2 will not work in all cases.

    • Adrian Rosebrock June 15, 2016 at 12:28 pm #

      Very true, thanks for pointing this out Andrew. However, if you’re using OpenCV prior to v2.4.0, you likely have other issues 🙂

  4. Swan August 22, 2016 at 8:02 pm #

    Thanks for providing imutils – it’s very useful!

    • Adrian Rosebrock August 24, 2016 at 12:21 pm #

      No problem! 🙂

  5. Rishabh November 7, 2016 at 12:57 pm #

    Awesome support.Thanks for the help.

    • Adrian Rosebrock November 7, 2016 at 2:40 pm #

      Glad I could help Rishabh!

  6. olivia October 31, 2017 at 3:47 pm #

    Hello again adrian,
    adrian i get an problem.
    when i want to check my opencv. i can’t find anything
    when i check the python, the last update of python was ini january.
    i following your step to install python dan opencv in middle of october, but i can’t find anything.
    but in the file manager opencv is already.
    could you help me adrian? thank you so much..

    • Adrian Rosebrock November 2, 2017 at 2:40 pm #

      Hi Olivia — I’m not sure what your question is here. What do you mean by “I can’t find anything”? You cannot import OpenCV into your Python scripts?

  7. lxw February 28, 2018 at 4:44 am #

    Bravo~ : )

  8. Agribot May 12, 2018 at 12:10 pm #

    Hi, I like your articles and I’ve purchased your on-line book.
    However …
    New-comers to this topic (Opencv, Python, etc) often experience problems with code examples caused by lack of clear information about what versions of the various items should be used ;- Python 2.7 ?? or 3.x ??, opencv 2.4 or 3.x ??, etc, etc

    I strongly recommend that ‘experts’ such as yourself add comments at the start of every program, such as;-

    “ ….Know to work with …Python X.X, opencv X.X, Windows X, …etc


    Versions required;- opencv X.x, imutils X.x or later, Python X.x (might not work with earlier versions) … “

    It may seem tedious or obvious to ‘Experts’, but lack of clarity about needed versions often causes problems for new-comers.

    Such information will help many people and will also will reduce the time needed later to fix bugs after they happen.

    Please, please do this going forward , thanks.

    (I’m using Python 2.7, cv2 2.4, imutils 0.4.6, Windows 7 home premium, service pack 1., 64 bit)


  1. How to find functions by name in OpenCV - PyImageSearch - August 31, 2015

    […] you’ll need to programmatically determine if a given function is available (whether via version detection or function […]

  2. Ball Tracking with OpenCV - PyImageSearch - September 14, 2015

    […] 2.4 and OpenCV 3. You can read more about why this change to cv2.findContours  is necessary in this blog post. We’ll also initialize the center  (x, y)-coordinates of the ball to None  on Line […]

  3. OpenCV 3 adoption rate - PyImageSearch - November 23, 2015

    […] example, with the release of OpenCV 3, common functions such as cv2.findContours  have different return signatures than OpenCV 2.4. The cv2.normalize  function signature has also changed. SIFT and SURF are no longer included in […]

  4. Multiple cameras with the Raspberry Pi and OpenCV - PyImageSearch - January 21, 2016

    […] care when examining Lines 43-45. As we know, the cv2.findContours  method return signature changed between OpenCV 2.4 and 3. This codeblock allows us to use cv2.findContours  in both OpenCV 2.4 and 3 without having to […]

  5. OpenCV center of contour - PyImageSearch - February 1, 2016

    […] A call to cv2.findContours  on Lines 20 and 21 returns the set of outlines (i.e., contours) that correspond to each of the white blobs on the image. Line 22 then grabs the appropriate tuple value based on whether we are using OpenCV 2.4 or OpenCV 3. You can read more about how the return signature of cv2.findContours  changed between OpenCV versions in this post. […]

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