Overview

This guide will help you install OpenCV for Python using python-pip package. You can use any Python distribution like Anaconda etc.

This is for Python users, instructions for C++ users are described in a different journal.

Introduction

It is 2025 and Apple MacBook Pro machines have moved on to Apple M2 CPUs and it’s not easy to keep up with the hardware (cost-wise). We are using an Apple Mac Pro 16″ from 2019 running iOS Sonoma 14.4 (it’s a few years old but good enough for what is needed for these experiments)…

Note that once we have our environment setup by following instructions below, we will be using two key commands from Terminal, to enter and exit the Virtual Environment where we will be executing Python commands and Scripts to process our OpenCV functions…

These are; workoncvcourse and deactivate.

user@Users-MacBook-Pro ~ % workoncvcourse

This switches us into the Virtual Environment

and

user@Users-MacBook-Pro ~ % deactivate

This switches us out of the Virtual Environment – back to normal Terminal Commands mode..

About this article

This article includes a step by step guide to show how to install OPCV, Python and dependencies on MacOS and assumes the user-name ‘user’.

However….It seems that the latest version of MacOS not only uses the theme of (user) profiles but it also defaults to user-zsh The problem with this is that after creating a Virtual Environment where we will be working on python Scripts, OpenCV libraries and commands and more significantly we want to create an ALIAS, which we would use to call up the virtual environment after starting up Terminal application.

The ‘profiles’ theme actually stops us from doing this. Because, when we start up Terminal, it presumes we’re user zsh and ignores the bash-script for ‘user’ where our ALIAS is stored.

For this reason, unless we switch to Profiles and create a profile before following instructions below – to make these effective for the profile(user-name) in question, we may be better off ignoring the ALIAS part and use the following command after starting up Terminal;

# Assume we have logged in as 'user' and fired up Terminal
# we should see the following command prompt..
user@Users-MacBook-Pro ~ %

# we then issue the following command - to fire up Virtual Environment
user@Users-MacBook-Pro ~ % source /Users/user/opencv-course/bin/activate
# this will then show that we're in the VirtEnv with..
(opencv-course) user@Users-MacBook-Pro ~ % 
#
# An example of what we can do from there
(opencv-course) user@Users-MacBook-Pro ~ % python sampleCode.py
(opencv-course) user@Users-MacBook-Pro ~ % 
# as can be seen, this command was executed without errors, which
# in this case was to generate a grayscale copy of the colour image
# using the CV2 library (as in the sampleCodepy script file (see below)

This is unfortunate but only due to the way latest versions of MacOS work. As shown below, we are running Sonoma 14.4.1

Step 1: Create a Virtual Environment

Assuming you have python installed on your system, we will use Virtual Environments to install Python libraries. It is generally a good practice in order to separate your project environment and global environment.

In [ ]:

# Current Working Directory = Print Working Directory
user@Users-MacBook-Pro ~ % cwd=$(pwd)

creating the virtual environment

# create virtual environment

user@Users-MacBook-Pro ~ % python3 –m venv opencv–course

python3 -m venv opencv-course

# bash_profile is a script that is executed each time you start a new shell.

We want to add a command in the script, where our Virtual Environment may be started by typing ‘workoncourse'<cr> in Terminal. This is known as an Alias…

Add comment into bash_profile script file

user@Users-MacBook-Pro ~ % echo "# Alias for OpenCV Course Virtual Environment" >> ~/.bash_profile

Add the alias

user@Users-MacBook-Pro ~ % echo “alias workoncvcourse=\”source $cwd/opencv-course/bin/activate\”” >> ~/.bash_profile

All of the above was for future-use.

Enter the Virtual Environment

user@Users-MacBook-Pro ~ % source “$cwd”/opencv-course/bin/activate

# Alternatively;
user@Users-MacBook-Pro ~ % source /Users/user/opencv-course/bin/activate

Upgrade pip and setup tools

# Upgrade pip and setup tools

Step 1 –
user@Users-MacBook-Pro ~ % pip install –upgrade pip

Step 2 –

user@Users-MacBook-Pro ~ % pip install –upgrade pip setuptools

(opencv-course) user@Users-MacBook-Pro ~ % pip install --upgrade pip setuptools
Requirement already satisfied: pip in ./opencv-course/lib/python3.12/site-packages (24.0)
Collecting pip
  Using cached pip-24.3.1-py3-none-any.whl.metadata (3.7 kB)
Collecting setuptools
  Using cached setuptools-75.6.0-py3-none-any.whl.metadata (6.7 kB)
Using cached pip-24.3.1-py3-none-any.whl (1.8 MB)
Using cached setuptools-75.6.0-py3-none-any.whl (1.2 MB)
Installing collected packages: setuptools, pip
  Attempting uninstall: pip
    Found existing installation: pip 24.0
    Uninstalling pip-24.0:
      Successfully uninstalled pip-24.0
Successfully installed pip-24.3.1 setuptools-75.6.0

Install Python Libraries

# now install python libraries within this virtual environment
pip install wheel numpy scipy matplotlib scikit–image scikit–learn ipython

(opencv-course) user@Users-MacBook-Pro ~ % pip install wheel numpy scipy matplotlib scikit-image scikit-learn ipython

Exit Virtual Environment

# quit virtual environment
opencv-course) user@Users-MacBook-Pro ~ % deactivate

Step 2: Install OpenCV

Now that we have created a virtual environment (opencv-course), we will activate it (using the alias) and then install OpenCV using pip.

In [ ]:

source ~/.bash_profile

# Activate the virtual environment
workoncvcourse<cr>

user@Users-MacBook-Pro ~ % source ~/.bash_profile
user@Users-MacBook-Pro ~ % workoncvcourse
(opencv-course) user@Users-MacBook-Pro ~ % 


# Install OpenCV
pip install opencv-contrib-python

(opencv-course) user@Users-MacBook-Pro ~ % 
(opencv-course) user@Users-MacBook-Pro ~ % pip install opencv-contrib-python
Collecting opencv-contrib-python
  Downloading opencv_contrib_python-4.10.0.84-cp37-abi3-macosx_12_0_x86_64.whl.metadata (20 kB)
Requirement already satisfied: numpy>=1.21.2 in ./opencv-course/lib/python3.12/site-packages (from opencv-contrib-python) (2.1.3)
Downloading opencv_contrib_python-4.10.0.84-cp37-abi3-macosx_12_0_x86_64.whl (66.3 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 66.3/66.3 MB 44.5 MB/s eta 0:00:00
Installing collected packages: opencv-contrib-python
Successfully installed opencv-contrib-python-4.10.0.84
(opencv-course) user@Users-MacBook-Pro ~ % 

Step 3: Check Installation

We are now at the final step of the installation. All that’s left to do is to verify if the installation worked.

# First, activate the environment.
user@Users-MacBook-Pro ~ % workoncvcourse<cr>

(opencv-course) user@Users-MacBook-Pro ~ % 

# open ipython (run this command on terminal)
ipython

(opencv-course) user@Users-MacBook-Pro ~ % ipython<cr>
Python 3.12.3 (v3.12.3:f6650f9ad7, Apr  9 2024, 08:18:48) [Clang 13.0.0 (clang-1300.0.29.30)]
Type 'copyright', 'credits' or 'license' for more information
IPython 8.29.0 -- An enhanced Interactive Python. Type '?' for help.

# 
# import cv2 and print the version (run following commands in ipython)
import cv2
print(cv2.__version__)

# If OpenCV is installed correctly, the above command should output OpenCV version

# The following is actual-input and output..

In [1]: import cv2
print(cv2.__version__)

In [2]: print(cv2.__version__)
4.10.0

In [3]:


# Press CTRL+D to exit ipython

# Now you can exit from Python virtual environment.
deactivate

Final Installation checks

If you try to run the sampleCode.py and get an error message, can’t open CV2 then you need to install the opencv-python modules within the Environment (the source of this very useful piece of information is https://sebhastian.com/modulenotfounderror-no-module-named-cv2/

And specifically, here’s the instructions for various OS…

Here’s a list of common install commands in popular Python environments to install the opencv-python package:

# if you don't have pip in your PATH:
python -m pip install opencv-python

python3 -m pip install opencv-python

# Windows
py -m pip install opencv-python

# Anaconda
conda install opencv-python

# Jupyter Notebook
!pip install opencv-python

# To check python installation inside the VirtEnv...
(opencv-course) user@Users-MacBook-Pro opencv-course % 
which -a python <cr>

# we see that it is at the following location
/Users/user/opencv-course/bin/python

# Let's install opencv-python for our VirtEnv....
(opencv-course) user@Users-MacBook-Pro opencv-course % python -m pip install opencv-python<cr>

Collecting opencv-python
  Downloading opencv_python-4.10.0.84-cp37-abi3-macosx_12_0_x86_64.whl (56.5 MB)
     |████████████████████████████████| 56.5 MB 54.7 MB/s 
Collecting numpy>=1.19.3
  Downloading numpy-2.0.2-cp39-cp39-macosx_14_0_x86_64.whl (6.9 MB)
     |████████████████████████████████| 6.9 MB 5.3 MB/s 
Installing collected packages: numpy, opencv-python
Successfully installed numpy-2.0.2 opencv-python-4.10.0.84

# DONE!! Now we can run our OpenCV Python Script...
  
(opencv-course) user@Users-MacBook-Pro opencv-course % python sampleCode.py<cr>
(opencv-course) user@Users-MacBook-Pro opencv-course %

Installation is complete. Now test sample code

Test OpenCV Installation using Sample Code

After installation of OpenCV. It’s time to test the installation using a sample code.

In this code, we will read a colour image of a boy and save its grayscale version. Below are the input and the expected output images.

Step 1: Download the sample code and image

Download the zip file containing the Python script, and the input image from here.. Next, extract the zip file into a folder (Finder:untitled/Users/user/opencv-course/–unzip-here—)

Step 2: Run the Python Script

Make sure you are in the extracted folder on the terminal. Then, use the following command:

It will not be evident that the following code has done anything, except that no errors are thrown.

Lines beneath it show the actual Python commands that are being executed.

Be sure that you have activated the virtual environment, before continuing. You can tell if you are in the virtual environment by the command prompt. I.e.

1 –

(opencv-course) user@Users-MacBook-Pro ~ % [you are in the virtual environment] – skip step 2 below…

2 –

user@Users-MacBook-Pro ~ % [ you are not in the virtual environment]

To enter VE, type the following (bold text)

user@Users-MacBook-Pro ~ % workoncvcourse<cr>

In [ ]:
python sampleCode.py

# Here's the code
In [2]: import cv2
In [3]: image = cv2.imread("boy.jpg", 0)
In [4]: cv2.imwrite("boyGray.jpg",image)
Out[4]: True

The code execution will generate a new file in the folder– boyGray.jpg. You can open the file and make sure it matches the expected output.

To exit the Virtual environment, type (bold text);

(opencv-course) user@Users-MacBook-Pro ~ % deactivate<cr>

user@Users-MacBook-Pro ~ %

Conclusions

We have shown how to create a Virtual Environment called opencv-course for the user in our /User/user/ folder, which we use for OpenCV development and experiments

We have shown how to create an Alias and inject it into our bash_profile so that we can enter the shortcut workoncourse from Terminal. This should take us directly to our Virtual Environment.

We have installed all the tools including Python and dependencies so as to be able to run OpenCV Scripts as well as execute interactive Python commands using iPython.

Enjoy!