MacOS: How to Fix the ‘Python.h’ Not Found Error With OpenCV?

'Python H' Not Found Error

Setting up OpenCV for Python development on MacOS can be tricky, especially when you run into cryptic compiler errors like “fatal error: ‘Python.h’ file not found”. This comprehensive guide will walk you through installing OpenCV 4.7.0 with Python 3.11 on MacOS, resolving the missing Python.h header file error, and verifying your OpenCV+Python installation.

This guide will show you how to:

  • Install OpenCV 4.7.0 with Python 3.11 bindings on MacOS
  • Resolve the “fatal error: ‘Python.h’ file not found” issue when compiling/installing OpenCV
  • Verify your OpenCV+Python installation to confirm everything is working

We’ll also look at some real-world examples of how this OpenCV+Python setup can be used for practical computer vision applications.

Also read: Troubleshooting OpenCV (cv2) Installation on Windows

Step 1 – Install Dependencies

OpenCV depends on several libraries like HDF5, NumPy, zlib etc. We’ll use Homebrew to install these dependencies:

brew install hdf5
brew install numpy
brew install libjpeg-turbo
brew install libpng
brew install libtiff  
brew install tbb
pip3 install scipy
Image 13

This will install all the required libraries. Make sure pip3 points to your Python 3.11 installation by running:

pip3 -V
# pip 22.3.1 from /usr/local/lib/python3.11/site-packages/pip (python 3.11)

If it points to a different Python version, update your PATH environment variable accordingly.

Also read: macOS – How To Run Python Script On The Terminal?

Step 2 – Install OpenCV 4.7.0

Let’s grab the OpenCV 4.7.0 source code and build/install it:

cd opencv-4.7.0
mkdir build
cd build

Now we can configure OpenCV’s build with our installed dependencies before compiling:

    -D CMAKE_INSTALL_PREFIX=/usr/local \
    -D PYTHON3_EXECUTABLE=/usr/local/bin/python3.11 \

make -j8

This configures OpenCV for our Python 3.11 installation, enables some optional modules, and kickstarts the compilation process.

You’ll likely see output like this showing OpenCV modules getting compiled:

[  6%] Building CXX object modules/core/CMakeFiles/opencv_core.dir/src/matrix.cpp.o
[  7%] Building CXX object modules/core/CMakeFiles/opencv_core.dir/src/matmul.cpp.o 

Finally, install the compiled OpenCV libraries:

sudo make install

If everything was successful, OpenCV is now installed! Let’s verify it.

Also read: Repeating a Video on Loop using OpenCV and Python

Step 3 – Resolve Python.h Not Found Error

When running the cmake command, you may run into an error like:

fatal error: 'Python.h' file not found 
#include <Python.h>

This means the OpenCV compiler cannot find the Python header files it needs to build the Python bindings.

The solution is to provide the path to Python’s include folder via C_INCLUDE_PATH before running cmake:

export C_INCLUDE_PATH=/usr/local/include/python3.11
cmake -D ...

On MacOS, the Python include folder is usually in /usr/local/include/pythonX.X where X.X is your Python version.

Adding this export before cmake resolves the missing Python.h issue for good!

Step 4 – Verify OpenCV+Python Install

To validate your OpenCV+Python installation, create a simple script:


import cv2

img = cv2.imread('image.jpg')
cv2.imshow('Image', img)

If this runs without errors and shows your image, then OpenCV is successfully installed!

You should see output like:


And an image window displaying your test image.

Some things to try:

  • Process a video stream from your webcam
  • Apply filters, and transformations to images
  • Detect and recognize faces or objects
  • Track colors, shapes etc.

The possibilities are endless!

Real-World Use Cases of OpenCV

Here are just some examples of how this OpenCV+Python setup can be used to build real-world computer vision apps:

  • Intelligent Video Surveillance – Apply object detection to identify people, vehicles, behaviors. Generate alerts for unauthorized access, violence detection etc.
  • Augmented Reality – Track camera motions, overlay 3D objects onto real world scenes for immersive AR experiences.
  • Image Enhancement – Upscale and improve quality of images/videos using super resolution algorithms. Color and lighting correction.
  • Facial Recognition – From attendance systems to photo album organization, facial recognition is a must-have today.
  • Autonomous Vehicles – Algorithms for real-time object detection, depth estimation, motion tracking and mapping for self-driving vehicles.

and many more use cases across healthcare, sports analytics, microscopy, agriculture, robotics etc!


Installing OpenCV for Python development on MacOS doesn’t have to be painful if you follow this guide. You now have OpenCV installed to build amazing Python apps for image processing, face recognition, object detection, augmented reality, and more! The key is having the right dependencies configured properly before compiling and installing OpenCV.